18 files changed, 248 insertions, 95 deletions
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 80000baf66..f68179841e 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -737,7 +737,7 @@ You can choose not to yield and build the response yourself, in which case the a
 
 While the most common way to use filters is by creating private methods and using *_action to add them, there are two other ways to do the same thing.
 
-The first is to use a block directly with the *_action methods. The block receives the controller as an argument, and the `require_login` filter from above could be rewritten to use a block:
+The first is to use a block directly with the *\_action methods. The block receives the controller as an argument, and the `require_login` filter from above could be rewritten to use a block:
 
 ```ruby
 class ApplicationController < ActionController::Base
diff --git a/guides/source/action_view_overview.md b/guides/source/action_view_overview.md
index 665a2b71ff..d3a2e15c61 100644
--- a/guides/source/action_view_overview.md
+++ b/guides/source/action_view_overview.md
@@ -190,6 +190,22 @@ One way to use partials is to treat them as the equivalent of subroutines; a way
 
 Here, the `_ad_banner.html.erb` and `_footer.html.erb` partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page.
 
+#### `render` without `partial` and `locals` options
+
+In the above example, `render` takes 2 options: `partial` and `locals`. But if
+these are the only options you want to pass, you can skip using these options.
+For example, instead of:
+
+```erb
+<%= render partial: "product", locals: {product: @product} %>
+```
+
+You can also do:
+
+```erb
+<%= render "product", product: @product %>
+```
+
 #### The `as` and `object` options
 
 By default `ActionView::Partials::PartialRenderer` has its object in a local variable with the same name as the template. So, given:
diff --git a/guides/source/active_record_migrations.md b/guides/source/active_record_migrations.md
index 97cabc1728..b8db21a989 100644
--- a/guides/source/active_record_migrations.md
+++ b/guides/source/active_record_migrations.md
@@ -479,7 +479,8 @@ Rails will generate a name for every foreign key starting with
 There is a `:name` option to specify a different name if needed.
 
 NOTE: Active Record only supports single column foreign keys. `execute` and
-`structure.sql` are required to use composite foreign keys.
+`structure.sql` are required to use composite foreign keys. See
+[Schema Dumping and You](#schema-dumping-and-you).
 
 Removing a foreign key is easy as well:
 
@@ -695,6 +696,10 @@ of `create_table` and `reversible`, replacing `create_table`
 by `drop_table`, and finally replacing `up` by `down` and vice-versa.
 This is all taken care of by `revert`.
 
+NOTE: If you want to add check constraints like in the examples above,
+you will have to use `structure.sql` as dump method. See
+[Schema Dumping and You](#schema-dumping-and-you).
+
 Running Migrations
 ------------------
 
@@ -943,10 +948,10 @@ that Active Record supports. This could be very useful if you were to
 distribute an application that is able to run against multiple databases.
 
 There is however a trade-off: `db/schema.rb` cannot express database specific
-items such as triggers, or stored procedures. While in a migration you can
-execute custom SQL statements, the schema dumper cannot reconstitute those
-statements from the database. If you are using features like this, then you
-should set the schema format to `:sql`.
+items such as triggers, stored procedures or check constraints. While in a
+migration you can execute custom SQL statements, the schema dumper cannot
+reconstitute those statements from the database. If you are using features like
+this, then you should set the schema format to `:sql`.
 
 Instead of using Active Record's schema dumper, the database's structure will
 be dumped using a tool specific to the database (via the `db:structure:dump`
diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index 373a98bb85..c5ca848753 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -343,6 +343,19 @@ end
 
 Another example would be if you wanted multiple workers handling the same processing queue. You could have each worker handle 10000 records by setting the appropriate `:start` option on each worker.
 
+**`:end_at`**
+
+Similar to the `:start` option, `:end_at` allows you to configure the last ID of the sequence whenever the highest ID is not the one you need.
+This would be useful, for example, if you wanted to run a batch process, using a subset of records based on `:start` and `:end_at`
+
+For example, to send newsletters only to users with the primary key starting from 2000 upto 10000 and to retrieve them in batches of 1000:
+
+```ruby
+User.find_each(start: 2000, end_at: 10000, batch_size: 5000) do |user|
+  NewsMailer.weekly(user).deliver_now
+end
+```
+
 #### `find_in_batches`
 
 The `find_in_batches` method is similar to `find_each`, since both retrieve batches of records. The difference is that `find_in_batches` yields _batches_ to the block as an array of models, instead of individually. The following example will yield to the supplied block an array of up to 1000 invoices at a time, with the final block containing any remaining invoices:
@@ -356,7 +369,7 @@ end
 
 ##### Options for `find_in_batches`
 
-The `find_in_batches` method accepts the same `:batch_size` and `:start` options as `find_each`.
+The `find_in_batches` method accepts the same `:batch_size`, `:start` and `:end_at` options as `find_each`.
 
 Conditions
 ----------
diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md
index 67cc6a4db3..93f76d3bf7 100644
--- a/guides/source/active_record_validations.md
+++ b/guides/source/active_record_validations.md
@@ -231,9 +231,9 @@ Errors](#working-with-validation-errors) section.
 
 ### `errors.details`
 
-To check what validator type was used on invalid attribute, you can use
-`errors.details[:attribute]`. It returns array of hashes where under `:error`
- key you will find symbol of used validator.
+To check which validations failed on an invalid attribute, you can use
+`errors.details[:attribute]`. It returns an array of hashes with an `:error`
+key to get the symbol of the validator:
 
 ```ruby
 class Person < ActiveRecord::Base
@@ -245,7 +245,7 @@ end
 >> person.errors.details[:name] #=> [{error: :blank}]
 ```
 
-Using `details` with custom validators are covered in the [Working with
+Using `details` with custom validators is covered in the [Working with
 Validation Errors](#working-with-validation-errors) section.
 
 Validation Helpers
@@ -1094,39 +1094,40 @@ Another way to do this is using `[]=` setter
 
 ### `errors.details`
 
-You can add validator type to details hash when using `errors.add` method.
+You can specify a validator type to the returned error details hash using the
+`errors.add` method.
 
 ```ruby
-  class Person < ActiveRecord::Base
-    def a_method_used_for_validation_purposes
-      errors.add(:name, :invalid_characters)
-    end
+class Person < ActiveRecord::Base
+  def a_method_used_for_validation_purposes
+    errors.add(:name, :invalid_characters)
   end
+end
 
-  person = Person.create(name: "!@#")
+person = Person.create(name: "!@#")
 
-  person.errors.details[:name]
-   # => [{error: :invalid_characters}]
+person.errors.details[:name]
+# => [{error: :invalid_characters}]
 ```
 
-To improve error details to contain not allowed characters set, you can
-pass additional options to `errors.add` method.
+To improve the error details to contain the unallowed characters set for instance,
+you can pass additional keys to `errors.add`.
 
 ```ruby
-  class Person < ActiveRecord::Base
-    def a_method_used_for_validation_purposes
-      errors.add(:name, :invalid_characters, not_allowed: "!@#%*()_-+=")
-    end
+class Person < ActiveRecord::Base
+  def a_method_used_for_validation_purposes
+    errors.add(:name, :invalid_characters, not_allowed: "!@#%*()_-+=")
   end
+end
 
-  person = Person.create(name: "!@#")
+person = Person.create(name: "!@#")
 
-  person.errors.details[:name]
-  # => [{error: :invalid_characters, not_allowed: "!@#%*()_-+="}]
+person.errors.details[:name]
+# => [{error: :invalid_characters, not_allowed: "!@#%*()_-+="}]
 ```
 
-All built in Rails validators populate details hash with corresponding
-validator types.
+All built in Rails validators populate the details hash with the corresponding
+validator type.
 
 ### `errors[:base]`
 
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index dab885a8fb..3484627a78 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -171,7 +171,7 @@ class CreateCustomers < ActiveRecord::Migration
     end
 
     create_table :orders do |t|
-      t.belongs_to :customer, index:true
+      t.belongs_to :customer, index: true
       t.datetime :order_date
       t.timestamps null: false
     end
@@ -691,7 +691,7 @@ c.first_name = 'Manny'
 c.first_name == o.customer.first_name # => false
 ```
 
-This happens because c and o.customer are two different in-memory representations of the same data, and neither one is automatically refreshed from changes to the other. Active Record provides the `:inverse_of` option so that you can inform it of these relations:
+This happens because `c` and `o.customer` are two different in-memory representations of the same data, and neither one is automatically refreshed from changes to the other. Active Record provides the `:inverse_of` option so that you can inform it of these relations:
 
 ```ruby
 class Customer < ActiveRecord::Base
@@ -726,10 +726,10 @@ Most associations with standard names will be supported. However, associations
 that contain the following options will not have their inverses set
 automatically:
 
-* :conditions
-* :through
-* :polymorphic
-* :foreign_key
+* `:conditions`
+* `:through`
+* `:polymorphic`
+* `:foreign_key`
 
 Detailed Association Reference
 ------------------------------
@@ -2243,3 +2243,67 @@ Extensions can refer to the internals of the association proxy using these three
 * `proxy_association.owner` returns the object that the association is a part of.
 * `proxy_association.reflection` returns the reflection object that describes the association.
 * `proxy_association.target` returns the associated object for `belongs_to` or `has_one`, or the collection of associated objects for `has_many` or `has_and_belongs_to_many`.
+
+Single Table Inheritance
+------------------------
+
+Sometimes, you may want to share fields and behavior between different models.
+Let's say we have Car, Motorcycle and Bicycle models. We will want to share
+the `color` and `price` fields and some methods for all of them, but having some
+specific behavior for each, and separated controllers too.
+
+Rails makes this quite easy. First, let's generate the base Vehicle model:
+
+```bash
+$ rails generate model vehicle type:string color:string price:decimal{10.2}
+```
+
+Did you note we are adding a "type" field? Since all models will be saved in a
+single database table, Rails will save in this column the name of the model that
+is being saved. In our example, this can be "Car", "Motorcycle" or "Bicycle."
+STI won't work without a "type" field in the table.
+
+Next, we will generate the three models that inherit from Vehicle. For this,
+we can use the `--parent=PARENT` option, which will generate a model that
+inherits from the specified parent and without equivalent migration (since the
+table already exists).
+
+For example, to generate the Car model:
+
+```bash
+$ rails generate model car --parent=Vehicle
+```
+
+The generated model will look like this:
+
+```ruby
+class Car < Vehicle
+end
+```
+
+This means that all behavior added to Vehicle is available for Car too, as
+associations, public methods, etc.
+
+Creating a car will save it in the `vehicles` table with "Car" as the `type` field:
+
+```ruby
+Car.create color: 'Red', price: 10000
+```
+
+will generate the following SQL:
+
+```sql
+INSERT INTO "vehicles" ("type", "color", "price") VALUES ("Car", "Red", 10000)
+```
+
+Querying car records will just search for vehicles that are cars:
+
+```ruby
+Car.all
+```
+
+will run a query like:
+
+```sql
+SELECT "vehicles".* FROM "vehicles" WHERE "vehicles"."type" IN ('Car')
+```
diff --git a/guides/source/autoloading_and_reloading_constants.md b/guides/source/autoloading_and_reloading_constants.md
index 202dc601a7..8f9125f311 100644
--- a/guides/source/autoloading_and_reloading_constants.md
+++ b/guides/source/autoloading_and_reloading_constants.md
@@ -151,9 +151,10 @@ executed, and popped after it.
 
 * A singleton class opened with `class << object` gets pushed, and popped later.
 
-* When any of the `*_eval` family of methods is called using a string argument,
+* When `instance_eval` is called using a string argument,
 the singleton class of the receiver is pushed to the nesting of the eval'ed
-code.
+code. When `class_eval` or `module_eval` is called using a string argument,
+the receiver is pushed to the nesting of the eval'ed code.
 
 * The nesting at the top-level of code interpreted by `Kernel#load` is empty
 unless the `load` call receives a true value as second argument, in which case
@@ -323,7 +324,7 @@ relative: `::Billing::Invoice`. That would force `Billing` to be looked up
 only as a top-level constant.
 
 `Invoice` on the other hand is qualified by `Billing` and we are going to see
-its resolution next. Let's call *parent* to that qualifying class or module
+its resolution next. Let's define *parent* to be that qualifying class or module
 object, that is, `Billing` in the example above. The algorithm for qualified
 constants goes like this:
 
@@ -460,8 +461,9 @@ Also, this collection is configurable via `config.autoload_paths`. For example,
 by adding this to `config/application.rb`:
 
 ```ruby
-config.autoload_paths += "#{Rails.root}/lib"
+config.autoload_paths << "#{Rails.root}/lib"
 ```
+`config.autoload_paths` is accessible from environment-specific configuration files, but any changes made to it outside `config/application.rb` don't have an effect.
 
 The value of `autoload_paths` can be inspected. In a just generated application
 it is (edited):
diff --git a/guides/source/command_line.md b/guides/source/command_line.md
index 78f26ccefa..19ccdc5488 100644
--- a/guides/source/command_line.md
+++ b/guides/source/command_line.md
@@ -419,14 +419,6 @@ The most common tasks of the `db:` Rake namespace are `migrate` and `create`, an
 
 More information about migrations can be found in the [Migrations](migrations.html) guide.
 
-### `doc`
-
-The `doc:` namespace has the tools to generate documentation for your app, API documentation, guides. Documentation can also be stripped which is mainly useful for slimming your codebase, like if you're writing a Rails application for an embedded platform.
-
-* `rake doc:app` generates documentation for your application in `doc/app`.
-* `rake doc:guides` generates Rails guides in `doc/guides`.
-* `rake doc:rails` generates API documentation for Rails in `doc/api`.
-
 ### `notes`
 
 `rake notes` will search through your code for comments beginning with FIXME, OPTIMIZE or TODO. The search is done in files with extension `.builder`, `.rb`, `.rake`, `.yml`, `.yaml`, `.ruby`, `.css`, `.js` and `.erb` for both default and custom annotations.
diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md
index 7381521658..e06706d750 100644
--- a/guides/source/contributing_to_ruby_on_rails.md
+++ b/guides/source/contributing_to_ruby_on_rails.md
@@ -173,6 +173,14 @@ $ git checkout -b my_new_branch
 
 It doesn't matter much what name you use, because this branch will only exist on your local computer and your personal repository on GitHub. It won't be part of the Rails Git repository.
 
+### Bundle Update
+
+Update and install the required gems.
+
+```bash
+$ bundle update
+```
+
 ### Running an Application Against Your Local Branch
 
 In case you need a dummy Rails app to test changes, the `--dev` flag of `rails new` generates an application that uses your local branch:
diff --git a/guides/source/debugging_rails_applications.md b/guides/source/debugging_rails_applications.md
index a788dd48ad..a2d2e93e3b 100644
--- a/guides/source/debugging_rails_applications.md
+++ b/guides/source/debugging_rails_applications.md
@@ -544,7 +544,7 @@ This way an irb session will be started within the context you invoked it. But
 be warned: this is an experimental feature.
 
 The `var` method is the most convenient way to show variables and their values.
-Let's let `byebug` to help us with it.
+Let's let `byebug` help us with it.
 
 ```
 (byebug) help var
@@ -832,7 +832,7 @@ application. Here is a list of useful plugins for debugging:
 * [Footnotes](https://github.com/josevalim/rails-footnotes) Every Rails page has
 footnotes that give request information and link back to your source via
 TextMate.
-* [Query Trace](https://github.com/ntalbott/query_trace/tree/master) Adds query
+* [Query Trace](https://github.com/ruckus/active-record-query-trace/tree/master) Adds query
 origin tracing to your logs.
 * [Query Reviewer](https://github.com/nesquena/query_reviewer) This rails plugin
 not only runs "EXPLAIN" before each of your select queries in development, but
diff --git a/guides/source/documents.yaml b/guides/source/documents.yaml
index 67032a31f5..7ae3640937 100644
--- a/guides/source/documents.yaml
+++ b/guides/source/documents.yaml
@@ -33,7 +33,7 @@
       url: active_record_querying.html
       description: This guide covers the database query interface provided by Active Record.
     -
-      name: Active Model basics
+      name: Active Model Basics
       url: active_model_basics.html
       description: This guide covers the use of model classes without Active Record.
       work_in_progress: true
diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md
index 4c02c99cc7..90004c611b 100644
--- a/guides/source/form_helpers.md
+++ b/guides/source/form_helpers.md
@@ -687,7 +687,14 @@ class LabellingFormBuilder < ActionView::Helpers::FormBuilder
 end
 ```
 
-If you reuse this frequently you could define a `labeled_form_for` helper that automatically applies the `builder: LabellingFormBuilder` option.
+If you reuse this frequently you could define a `labeled_form_for` helper that automatically applies the `builder: LabellingFormBuilder` option:
+
+```ruby
+def labeled_form_for(record, options = {}, &block)
+  options.merge! builder: LabellingFormBuilder
+  form_for record, options, &block
+end
+```
 
 The form builder used also determines what happens when you do
 
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md
index 5945d48e98..51b8a2ca5f 100644
--- a/guides/source/getting_started.md
+++ b/guides/source/getting_started.md
@@ -193,6 +193,9 @@ following in the `blog` directory:
 $ bin/rails server
 ```
 
+TIP: If you are using Windows, you have to pass the scripts under the `bin`
+folder directly to the Ruby interpreter e.g. `ruby bin\rails server`.
+
 TIP: Compiling CoffeeScript and JavaScript asset compression requires you
 have a JavaScript runtime available on your system, in the absence
 of a runtime you will see an `execjs` error during asset compilation.
@@ -908,6 +911,7 @@ And then finally, add the view for this action, located at
     <tr>
       <td><%= article.title %></td>
       <td><%= article.text %></td>
+      <td><%= link_to 'Show', article_path(article) %></td>
     </tr>
   <% end %>
 </table>
@@ -2051,19 +2055,6 @@ resources:
 * The [Ruby on Rails mailing list](http://groups.google.com/group/rubyonrails-talk)
 * The [#rubyonrails](irc://irc.freenode.net/#rubyonrails) channel on irc.freenode.net
 
-Rails also comes with built-in help that you can generate using the rake
-command-line utility:
-
-* Running `rake doc:guides` will put a full copy of the Rails Guides in the
-  `doc/guides` folder of your application. Open `doc/guides/index.html` in your
-  web browser to explore the Guides.
-* Running `rake doc:rails` will put a full copy of the API documentation for
-  Rails in the `doc/api` folder of your application. Open `doc/api/index.html`
-  in your web browser to explore the API documentation.
-
-TIP: To be able to generate the Rails Guides locally with the `doc:guides` rake
-task you need to install the Redcarpet and Nokogiri gems. Add it to your `Gemfile` and run
-`bundle install` and you're ready to go.
 
 Configuration Gotchas
 ---------------------
diff --git a/guides/source/i18n.md b/guides/source/i18n.md
index fbee267975..9b049ea8b8 100644
--- a/guides/source/i18n.md
+++ b/guides/source/i18n.md
@@ -588,6 +588,26 @@ you can look up the `books.index.title` value **inside** `app/views/books/index.
 
 NOTE: Automatic translation scoping by partial is only available from the `translate` view helper method.
 
+"Lazy" lookup can also be used in controllers:
+
+```yaml
+en:
+  books:
+    create:
+      success: Book created!
+```
+
+This is useful for setting flash messages for instance:
+
+```ruby
+class BooksController < ApplicationController
+  def create
+    # ...
+    redirect_to books_url, notice: t('.success')
+  end
+end
+```
+
 ### Interpolation
 
 In many cases you want to abstract your translations so that **variables can be interpolated into the translation**. For this reason the I18n API provides an interpolation feature.
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
index 69d3f6e86c..b7fc580939 100644
--- a/guides/source/layouts_and_rendering.md
+++ b/guides/source/layouts_and_rendering.md
@@ -1049,7 +1049,7 @@ As you already could see from the previous sections of this guide, `yield` is a
       <p>
         Name contains: <%= f.text_field :name_contains %>
       </p>
-    <%= end %>
+    <% end %>
     ```
 
 * `roles/index.html.erb`
@@ -1059,7 +1059,7 @@ As you already could see from the previous sections of this guide, `yield` is a
       <p>
         Title contains: <%= f.text_field :title_contains %>
       </p>
-    <%= end %>
+    <% end %>
     ```
 
 * `shared/_search_filters.html.erb`
diff --git a/guides/source/testing.md b/guides/source/testing.md
index fa55c09c64..14bc75aa7d 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -120,9 +120,9 @@ user_<%= n %>:
 
 Rails by default automatically loads all fixtures from the `test/fixtures` directory for your models and controllers test. Loading involves three steps:
 
-* Remove any existing data from the table corresponding to the fixture
-* Load the fixture data into the table
-* Dump the fixture data into a method in case you want to access it directly
+1. Remove any existing data from the table corresponding to the fixture
+2. Load the fixture data into the table
+3. Dump the fixture data into a method in case you want to access it directly
 
 TIP: In order to remove existing data from the database, Rails tries to disable referential integrity triggers (like foreign keys and check constraints). If you are getting annoying permission errors on running tests, make sure the database user has privilege to disable these triggers in testing environment. (In PostgreSQL, only superusers can disable all triggers. Read more about PostgreSQL permissions [here](http://blog.endpoint.com/2012/10/postgres-system-triggers-error.html))
 
@@ -270,6 +270,8 @@ Finished tests in 0.009262s, 107.9680 tests/s, 107.9680 assertions/s.
 1 tests, 1 assertions, 0 failures, 0 errors, 0 skips
 ```
 
+This will run all test methods from the test case.
+
 You can also run a particular test method from the test case by running the test and providing the `test method name`.
 
 ```bash
@@ -281,8 +283,6 @@ Finished tests in 0.009064s, 110.3266 tests/s, 110.3266 assertions/s.
 1 tests, 1 assertions, 0 failures, 0 errors, 0 skips
 ```
 
-This will run all test methods from the test case.
-
 The `.` (dot) above indicates a passing test. When a test fails you see an `F`; when a test throws an error you see an `E` in its place. The last line of the output is the summary.
 
 #### Your first failing test
@@ -347,7 +347,11 @@ Finished tests in 0.047721s, 20.9551 tests/s, 20.9551 assertions/s.
 1 tests, 1 assertions, 0 failures, 0 errors, 0 skips
 ```
 
-Now, if you noticed, we first wrote a test which fails for a desired functionality, then we wrote some code which adds the functionality and finally we ensured that our test passes. This approach to software development is referred to as _Test-Driven Development_ (TDD).
+Now, if you noticed, we first wrote a test which fails for a desired
+functionality, then we wrote some code which adds the functionality and finally
+we ensured that our test passes. This approach to software development is
+referred to as
+[_Test-Driven Development_ (TDD)](http://c2.com/cgi/wiki?TestDrivenDevelopment).
 
 #### What an error looks like
 
@@ -379,7 +383,11 @@ NameError: undefined local variable or method `some_undefined_variable' for #<Ar
 
 Notice the 'E' in the output. It denotes a test with error.
 
-NOTE: The execution of each test method stops as soon as any error or an assertion failure is encountered, and the test suite continues with the next method. All test methods are executed in alphabetical order.
+NOTE: The execution of each test method stops as soon as any error or an
+assertion failure is encountered, and the test suite continues with the next
+method. All test methods are executed in random order. The
+[`config.active_support.test_order` option](http://edgeguides.rubyonrails.org/configuring.html#configuring-active-support)
+can be used to configure test order.
 
 When a test fails you are presented with the corresponding backtrace. By default
 Rails filters that backtrace and will only print lines relevant to your
@@ -480,21 +488,28 @@ In the `test_should_get_index` test, Rails simulates a request on the action cal
 
 The `get` method kicks off the web request and populates the results into the response. It accepts 4 arguments:
 
-* The action of the controller you are requesting. This can be in the form of a string or a symbol.
-* An optional hash of request parameters to pass into the action (eg. query string parameters or article variables).
-* An optional hash of session variables to pass along with the request.
-* An optional hash of flash values.
+* The action of the controller you are requesting.
+  This can be in the form of a string or a symbol.
+
+* `params`: option with a hash of request parameters to pass into the action
+  (e.g. query string parameters or article variables).
+
+* `session`: option with a hash of session variables to pass along with the request.
+
+* `flash`: option with a hash of flash values.
+
+All the keyword arguments are optional.
 
 Example: Calling the `:show` action, passing an `id` of 12 as the `params` and setting a `user_id` of 5 in the session:
 
 ```ruby
-get(:show, {'id' => "12"}, {'user_id' => 5})
+get(:show, params: { 'id' => "12" }, session: { 'user_id' => 5 })
 ```
 
 Another example: Calling the `:view` action, passing an `id` of 12 as the `params`, this time with no session, but with a flash message.
 
 ```ruby
-get(:view, {'id' => '12'}, nil, {'message' => 'booya!'})
+get(:view, params: { 'id' => '12' }, flash: { 'message' => 'booya!' })
 ```
 
 NOTE: If you try running `test_should_create_article` test from `articles_controller_test.rb` it will fail on account of the newly added model level validation and rightly so.
@@ -504,7 +519,7 @@ Let us modify `test_should_create_article` test in `articles_controller_test.rb`
 ```ruby
 test "should create article" do
   assert_difference('Article.count') do
-    post :create, article: {title: 'Some title'}
+    post :create, params: { article: { title: 'Some title' } }
   end
 
   assert_redirected_to article_path(assigns(:article))
@@ -530,11 +545,12 @@ NOTE: Functional tests do not verify whether the specified request type is accep
 
 ### Testing XHR (AJAX) requests
 
-`xhr` accepts method (listed in the section above), action name and parameters:
+To test AJAX requests, you can specify the `xhr: true` option to `get`, `post`,
+`patch`, `put`, and `delete` methods:
 
 ```ruby
 test "ajax request responds with no layout" do
-  xhr :get, :show, id: articles(:first).id
+  get :show, params: { id: articles(:first).id }, xhr: true
 
   assert_template :index
   assert_template layout: nil
@@ -638,7 +654,7 @@ Let's start by adding this assertion to our `test_should_create_article` test:
 ```ruby
 test "should create article" do
   assert_difference('Article.count') do
-    post :create, article: {title: 'Some title'}
+    post :create, params: { article: { title: 'Some title' } }
   end
 
   assert_redirected_to article_path(assigns(:article))
@@ -708,7 +724,7 @@ Let's write a test for the `:show` action:
 ```ruby
 test "should show article" do
   article = articles(:one)
-  get :show, id: article.id
+  get :show, params: { id: article.id }
   assert_response :success
 end
 ```
@@ -721,7 +737,7 @@ How about deleting an existing Article?
 test "should destroy article" do
   article = articles(:one)
   assert_difference('Article.count', -1) do
-    delete :destroy, id: article.id
+    delete :destroy, params: { id: article.id }
   end
 
   assert_redirected_to articles_path
@@ -733,7 +749,7 @@ We can also add a test for updating an existing Article.
 ```ruby
 test "should update article" do
   article = articles(:one)
-  patch :update, id: article.id, article: {title: "updated"}
+  patch :update, params: { id: article.id, article: { title: "updated" } }
   assert_redirected_to article_path(assigns(:article))
 end
 ```
@@ -759,20 +775,20 @@ class ArticlesControllerTest < ActionController::TestCase
 
   test "should show article" do
     # Reuse the @article instance variable from setup
-    get :show, id: @article.id
+    get :show, params: { id: @article.id }
     assert_response :success
   end
 
   test "should destroy article" do
     assert_difference('Article.count', -1) do
-      delete :destroy, id: @article.id
+      delete :destroy, params: { id: @article.id }
     end
 
     assert_redirected_to articles_path
   end
 
   test "should update article" do
-    patch :update, id: @article.id, article: {title: "updated"}
+    patch :update, params: { id: @article.id, article: { title: "updated" } }
     assert_redirected_to article_path(assigns(:article))
   end
 end
@@ -1026,7 +1042,8 @@ test "can create an article" do
   assert_response :success
   assert_template "articles/new", partial: "articles/_form"
 
-  post "/articles", article: {title: "can create", body: "article successfully."}
+  post "/articles",
+    params: { article: { title: "can create", body: "article successfully." } }
   assert_response :redirect
   follow_redirect!
   assert_response :success
@@ -1042,7 +1059,8 @@ We start by calling the `:new` action on our Articles controller. This response
 After this we make a post request to the `:create` action of our Articles controller:
 
 ```ruby
-post "/articles", article: {title: "can create", body: "article successfully."}
+post "/articles",
+  params: { article: { title: "can create", body: "article successfully." } }
 assert_response :redirect
 follow_redirect!
 ```
@@ -1147,7 +1165,7 @@ require 'test_helper'
 class UserControllerTest < ActionController::TestCase
   test "invite friend" do
     assert_difference 'ActionMailer::Base.deliveries.size', +1 do
-      post :invite_friend, email: 'friend@example.com'
+      post :invite_friend, params: { email: 'friend@example.com' }
     end
     invite_email = ActionMailer::Base.deliveries.last
 
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index d7fbe575c2..20b90bdba0 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -276,6 +276,22 @@ class Notifier < ActionMailer::Base
 end
 ```
 
+### Foreign Key Support
+
+The migration DSL has been expanded to support foreign key definitions. If
+you've been using the Foreigner gem, you might want to consider removing it.
+Note that the foreign key support of Rails is a subset of Foreigner. This means
+that not every Foreigner definition can be fully replaced by it's Rails
+migration DSL counterpart.
+
+The migration procedure is as follows:
+
+1. remove `gem "foreigner"` from the Gemfile.
+2. run `bundle install`.
+3. run `bin/rake db:schema:dump`.
+4. make sure that `db/schema.rb` contains every foreign key definition with
+the necessary options.
+
 Upgrading from Rails 4.0 to Rails 4.1
 -------------------------------------
 
@@ -534,7 +550,7 @@ module FixtureFileHelpers
     Digest::SHA2.hexdigest(File.read(Rails.root.join('test/fixtures', path)))
   end
 end
-ActiveRecord::FixtureSet.context_class.send :include, FixtureFileHelpers
+ActiveRecord::FixtureSet.context_class.include FixtureFileHelpers
 ```
 
 ### I18n enforcing available locales
diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md
index 367abddcfa..f3d3a83afc 100644
--- a/guides/source/working_with_javascript_in_rails.md
+++ b/guides/source/working_with_javascript_in_rails.md
@@ -357,7 +357,7 @@ This gem uses Ajax to speed up page rendering in most applications.
 
 Turbolinks attaches a click handler to all `<a>` on the page. If your browser
 supports
-[PushState](https://developer.mozilla.org/en-US/docs/DOM/Manipulating_the_browser_history#The_pushState(\).C2.A0method),
+[PushState](https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history#The_pushState()_method),
 Turbolinks will make an Ajax request for the page, parse the response, and
 replace the entire `<body>` of the page with the `<body>` of the response. It
 will then use PushState to change the URL to the correct one, preserving