13 files changed, 61 insertions, 38 deletions
diff --git a/guides/source/2_2_release_notes.md b/guides/source/2_2_release_notes.md
index 79634d8760..c6bac34d18 100644
--- a/guides/source/2_2_release_notes.md
+++ b/guides/source/2_2_release_notes.md
@@ -34,7 +34,7 @@ Documentation
 The internal documentation of Rails, in the form of code comments, has been improved in numerous places. In addition, the [Ruby on Rails Guides](http://guides.rubyonrails.org/) project is the definitive source for information on major Rails components. In its first official release, the Guides page includes:
 
 * [Getting Started with Rails](getting_started.html)
-* [Rails Database Migrations](migrations.html)
+* [Rails Database Migrations](active_record_migrations.html)
 * [Active Record Associations](association_basics.html)
 * [Active Record Query Interface](active_record_querying.html)
 * [Layouts and Rendering in Rails](layouts_and_rendering.html)
diff --git a/guides/source/5_0_release_notes.md b/guides/source/5_0_release_notes.md
index b542005f52..3710247582 100644
--- a/guides/source/5_0_release_notes.md
+++ b/guides/source/5_0_release_notes.md
@@ -91,9 +91,9 @@ without having to rely on implementation details or monkey patching.
 
 Some things that you can achieve with this:
 
-* The type detected by Active Record can be overridden.
-* A default can also be provided.
-* Attributes do not need to be backed by a database column.
+- The type detected by Active Record can be overridden.
+- A default can also be provided.
+- Attributes do not need to be backed by a database column.
 
 ```ruby
 
@@ -206,7 +206,7 @@ Please refer to the [Changelog][railties] for detailed changes.
 
 *   Deprecated `config.static_cache_control` in favor of
     `config.public_file_server.headers`.
-    ([Pull Request](https://github.com/rails/rails/pull/22173))
+    ([Pull Request](https://github.com/rails/rails/pull/19135))
 
 *   Deprecated `config.serve_static_files` in favor of `config.public_file_server.enabled`.
     ([Pull Request](https://github.com/rails/rails/pull/22173))
diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md
index d9e9466a33..6b3aa471f9 100644
--- a/guides/source/active_record_basics.md
+++ b/guides/source/active_record_basics.md
@@ -104,7 +104,7 @@ depending on the purpose of these columns.
   your models.
 * **Primary keys** - By default, Active Record will use an integer column named
   `id` as the table's primary key. When using [Active Record
-  Migrations](migrations.html) to create your tables, this column will be
+  Migrations](active_record_migrations.html) to create your tables, this column will be
   automatically created.
 
 There are also some optional column names that will add additional features
@@ -374,4 +374,4 @@ and to roll it back, `rails db:rollback`.
 
 Note that the above code is database-agnostic: it will run in MySQL,
 PostgreSQL, Oracle and others. You can learn more about migrations in the
-[Active Record Migrations guide](migrations.html).
+[Active Record Migrations guide](active_record_migrations.html).
diff --git a/guides/source/active_record_migrations.md b/guides/source/active_record_migrations.md
index f914122242..a45becf670 100644
--- a/guides/source/active_record_migrations.md
+++ b/guides/source/active_record_migrations.md
@@ -241,7 +241,7 @@ generates
 ```ruby
 class AddUserRefToProducts < ActiveRecord::Migration[5.0]
   def change
-    add_reference :products, :user, index: true, foreign_key: true
+    add_reference :products, :user, foreign_key: true
   end
 end
 ```
@@ -313,7 +313,7 @@ will produce a migration that looks like this
 class AddDetailsToProducts < ActiveRecord::Migration[5.0]
   def change
     add_column :products, :price, :decimal, precision: 5, scale: 2
-    add_reference :products, :supplier, polymorphic: true, index: true
+    add_reference :products, :supplier, polymorphic: true
   end
 end
 ```
diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index 928ab43b3b..90f200133b 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -204,7 +204,7 @@ The SQL equivalent of the above is:
 SELECT * FROM clients ORDER BY clients.id ASC LIMIT 3
 ```
 
-On a collection that is ordered using `order`, `first` will return the first record ordered by the specified attribute for `order`. 
+On a collection that is ordered using `order`, `first` will return the first record ordered by the specified attribute for `order`.
 
 ```ruby
 client = Client.order(:first_name).first
@@ -255,7 +255,7 @@ The SQL equivalent of the above is:
 SELECT * FROM clients ORDER BY clients.id DESC LIMIT 3
 ```
 
-On a collection that is ordered using `order`, `last` will return the last record ordered by the specified attribute for `order`. 
+On a collection that is ordered using `order`, `last` will return the last record ordered by the specified attribute for `order`.
 
 ```ruby
 client = Client.order(:first_name).last
@@ -314,7 +314,7 @@ We often need to iterate over a large set of records, as when we send a newslett
 This may appear straightforward:
 
 ```ruby
-# This is very inefficient when the users table has thousands of rows.
+# This may consume too much memory if the table is big.
 User.all.each do |user|
   NewsMailer.weekly(user).deliver_now
 end
@@ -328,7 +328,7 @@ TIP: The `find_each` and `find_in_batches` methods are intended for use in the b
 
 #### `find_each`
 
-The `find_each` method retrieves a batch of records and then yields _each_ record to the block individually as a model. In the following example, `find_each` will retrieve 1000 records (the current default for both `find_each` and `find_in_batches`) and then yield each record individually to the block as a model. This process is repeated until all of the records have been processed:
+The `find_each` method retrieves records in batches and then yields _each_ one to the block. In the following example, `find_each` retrieves users in batches of 1000 and yields them to the block one by one:
 
 ```ruby
 User.find_each do |user|
@@ -336,7 +336,9 @@ User.find_each do |user|
 end
 ```
 
-To add conditions to a `find_each` operation you can chain other Active Record methods such as `where`:
+This process is repeated, fetching more batches as needed, until all of the records have been processed.
+
+`find_each` works on model classes, as seen above, and also on relations:
 
 ```ruby
 User.where(weekly_subscriber: true).find_each do |user|
@@ -344,11 +346,16 @@ User.where(weekly_subscriber: true).find_each do |user|
 end
 ```
 
-##### Options for `find_each`
+as long as they have no ordering, since the method needs to force an order
+internally to iterate.
 
-The `find_each` method accepts most of the options allowed by the regular `find` method, except for `:order` and `:limit`, which are reserved for internal use by `find_each`.
+If an order is present in the receiver the behaviour depends on the flag
+`config.active_record.error_on_ignored_order`. If true, `ArgumentError` is
+raised, otherwise the order is ignored and a warning issued, which is the
+default. This can be overridden with the option `:error_on_ignore`, explained
+below.
 
-Three additional options, `:batch_size`, `:start` and `:finish`, are available as well.
+##### Options for `find_each`
 
 **`:batch_size`**
 
@@ -364,10 +371,10 @@ end
 
 By default, records are fetched in ascending order of the primary key, which must be an integer. The `:start` option allows you to configure the first ID of the sequence whenever the lowest ID is not the one you need. This would be useful, for example, if you wanted to resume an interrupted batch process, provided you saved the last processed ID as a checkpoint.
 
-For example, to send newsletters only to users with the primary key starting from 2000, and to retrieve them in batches of 5000:
+For example, to send newsletters only to users with the primary key starting from 2000:
 
 ```ruby
-User.find_each(start: 2000, batch_size: 5000) do |user|
+User.find_each(start: 2000) do |user|
   NewsMailer.weekly(user).deliver_now
 end
 ```
@@ -375,12 +382,12 @@ end
 **`:finish`**
 
 Similar to the `:start` option, `:finish` 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 `:finish`
+This would be useful, for example, if you wanted to run a batch process using a subset of records based on `:start` and `:finish`.
 
-For example, to send newsletters only to users with the primary key starting from 2000 up to 10000 and to retrieve them in batches of 5000:
+For example, to send newsletters only to users with the primary key starting from 2000 up to 10000:
 
 ```ruby
-User.find_each(start: 2000, finish: 10000, batch_size: 5000) do |user|
+User.find_each(start: 2000, finish: 10000) do |user|
   NewsMailer.weekly(user).deliver_now
 end
 ```
@@ -389,20 +396,36 @@ 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` and `:finish` options on each worker.
 
+**`:error_on_ignore`**
+
+Overrides the application config to specify if an error should be raised when an
+order is present in the relation.
+
 #### `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:
 
 ```ruby
-# Give add_invoices an array of 1000 invoices at a time
+# Give add_invoices an array of 1000 invoices at a time.
 Invoice.find_in_batches do |invoices|
   export.add_invoices(invoices)
 end
 ```
 
+`find_in_batches` works on model classes, as seen above, and also on relations:
+
+```ruby
+Invoice.pending.find_in_batches do |invoice|
+  pending_invoices_export.add_invoices(invoices)
+end
+```
+
+as long as they have no ordering, since the method needs to force an order
+internally to iterate.
+
 ##### Options for `find_in_batches`
 
-The `find_in_batches` method accepts the same `:batch_size`, `:start` and `:finish` options as `find_each`.
+The `find_in_batches` method accepts the same options as `find_each`.
 
 Conditions
 ----------
diff --git a/guides/source/command_line.md b/guides/source/command_line.md
index f766403228..42276bcb90 100644
--- a/guides/source/command_line.md
+++ b/guides/source/command_line.md
@@ -209,7 +209,7 @@ Description:
     Create rails files for model generator.
 ```
 
-NOTE: For a list of available field types, refer to the [API documentation](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html#method-i-column) for the column method for the `TableDefinition` class.
+NOTE: For a list of available field types for the `type` parameter, refer to the [API documentation](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_column) for the add_column method for the `SchemaStatements` module. The `index` parameter generates a corresponding index for the column.
 
 But instead of generating a model directly (which we'll be doing later), let's set up a scaffold. A **scaffold** in Rails is a full set of model, database migration for that model, controller to manipulate it, views to view and manipulate the data, and a test suite for each of the above.
 
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index 34878e5c38..d11edf2bfa 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -163,7 +163,7 @@ pipeline is enabled. It is set to `true` by default.
 
 * `config.assets.js_compressor` defines the JavaScript compressor to use. Possible values are `:closure`, `:uglifier` and `:yui` which require the use of the `closure-compiler`, `uglifier` or `yui-compressor` gems respectively.
 
-* `config.assets.gzip` a flag that enables the creation of gzipped version of compiled assets, along with non-gzipped assets. Set to `true` by default.  
+* `config.assets.gzip` a flag that enables the creation of gzipped version of compiled assets, along with non-gzipped assets. Set to `true` by default.
 
 * `config.assets.paths` contains the paths which are used to look for assets. Appending paths to this configuration option will cause those paths to be used in the search for assets.
 
@@ -297,7 +297,7 @@ All these configuration options are delegated to the `I18n` library.
   * Or you can set different fallbacks for locales individually. For example, if you want to use `:tr` for `:az` and `:de`, `:en` for `:da` as fallbacks, you can do it, like so:
 
     ```ruby
-    config.i18n.fallbacks = { az: :tr, da: [:de, :en] } 
+    config.i18n.fallbacks = { az: :tr, da: [:de, :en] }
     #or
     config.i18n.fallbacks.map = { az: :tr, da: [:de, :en] }
     ```
@@ -324,7 +324,7 @@ All these configuration options are delegated to the `I18n` library.
 
 * `config.active_record.schema_format` controls the format for dumping the database schema to a file. The options are `:ruby` (the default) for a database-independent version that depends on migrations, or `:sql` for a set of (potentially database-dependent) SQL statements.
 
-* `config.active_record.error_on_ignored_order_or_limit` specifies if an error should be raised if the order or limit of a query is ignored during a batch query. The options are `true` (raise error) or `false` (warn). Default is `false`.
+* `config.active_record.error_on_ignored_order` specifies if an error should be raised if the order of a query is ignored during a batch query. The options are `true` (raise error) or `false` (warn). Default is `false`.
 
 * `config.active_record.timestamped_migrations` controls whether migrations are numbered with serial integers or with timestamps. The default is `true`, to use timestamps, which are preferred if there are multiple developers working on the same application.
 
@@ -529,7 +529,7 @@ There are a number of settings available on `config.action_mailer`:
     * `:authentication` - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of `:plain`, `:login`, `:cram_md5`.
     * `:enable_starttls_auto` - Detects if STARTTLS is enabled in your SMTP server and starts to use it. It defaults to `true`.
     * `:openssl_verify_mode` - When using TLS, you can set how OpenSSL checks the certificate. This is useful if you need to validate a self-signed and/or a wildcard certificate. This can be one of the OpenSSL verify constants, `:none` or `:peer` -- or the constant directly `OpenSSL::SSL::VERIFY_NONE` or `OpenSSL::SSL::VERIFY_PEER`, respectively.
-    * `:ssl/:tls` - Enables the SMTP connection to use SMTP/TLS (SMTPS: SMTP over direct TLS connection).                                  
+    * `:ssl/:tls` - Enables the SMTP connection to use SMTP/TLS (SMTPS: SMTP over direct TLS connection).
 
 * `config.action_mailer.sendmail_settings` allows detailed configuration for the `sendmail` delivery method. It accepts a hash of options, which can include any of these options:
     * `:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`.
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md
index b0d3953cbd..0f1c3735e8 100644
--- a/guides/source/getting_started.md
+++ b/guides/source/getting_started.md
@@ -700,8 +700,8 @@ in case you want to reverse it later. When you run this migration it will create
 an `articles` table with one string column and a text column. It also creates
 two timestamp fields to allow Rails to track article creation and update times.
 
-TIP: For more information about migrations, refer to [Rails Database Migrations]
-(migrations.html).
+TIP: For more information about migrations, refer to [Active Record Migrations]
+(active_record_migrations.html).
 
 At this point, you can use a bin/rails command to run the migration:
 
diff --git a/guides/source/i18n.md b/guides/source/i18n.md
index f3802a142f..850f0def03 100644
--- a/guides/source/i18n.md
+++ b/guides/source/i18n.md
@@ -1120,7 +1120,7 @@ Contributing to Rails I18n
 
 I18n support in Ruby on Rails was introduced in the release 2.2 and is still evolving. The project follows the good Ruby on Rails development tradition of evolving solutions in gems and real applications first, and only then cherry-picking the best-of-breed of most widely useful features for inclusion in the core.
 
-Thus we encourage everybody to experiment with new ideas and features in gems or other libraries and make them available to the community. (Don't forget to announce your work on our [mailing list](http://groups.google.com/group/rails-i18n!))
+Thus we encourage everybody to experiment with new ideas and features in gems or other libraries and make them available to the community. (Don't forget to announce your work on our [mailing list](http://groups.google.com/group/rails-i18n)!)
 
 If you find your own locale (language) missing from our [example translations data](https://github.com/svenfuchs/rails-i18n/tree/master/rails/locale) repository for Ruby on Rails, please [_fork_](https://github.com/guides/fork-a-project-and-submit-your-modifications) the repository, add your data and send a [pull request](https://github.com/guides/pull-requests).
 
diff --git a/guides/source/plugins.md b/guides/source/plugins.md
index 8f055f8fe3..ff84861b8c 100644
--- a/guides/source/plugins.md
+++ b/guides/source/plugins.md
@@ -30,7 +30,7 @@ Setup
 -----
 
 Currently, Rails plugins are built as gems, _gemified plugins_. They can be shared across
-different rails applications using RubyGems and Bundler if desired.
+different Rails applications using RubyGems and Bundler if desired.
 
 ### Generate a gemified plugin.
 
diff --git a/guides/source/security.md b/guides/source/security.md
index ca985134e6..2d1bc3b5b3 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -249,7 +249,7 @@ There are many other possibilities, like using a `<script>` tag to make a cross-
 
 Note: We can't distinguish a `<script>` tag's origin—whether it's a tag on your own site or on some other malicious site—so we must block all `<script>` across the board, even if it's actually a safe same-origin script served from your own site. In these cases, explicitly skip CSRF protection on actions that serve JavaScript meant for a `<script>` tag.
 
-To protect against all other forged requests, we introduce a _required security token_ that our site knows but other sites don't know. We include the security token in requests and verify it on the server. This is a one-liner in your application controller, and is the default for newly created rails applications:
+To protect against all other forged requests, we introduce a _required security token_ that our site knows but other sites don't know. We include the security token in requests and verify it on the server. This is a one-liner in your application controller, and is the default for newly created Rails applications:
 
 ```ruby
 protect_from_forgery with: :exception
diff --git a/guides/source/testing.md b/guides/source/testing.md
index 440d87bf73..26d50bec0c 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -879,10 +879,10 @@ can be passed as headers:
 
 ```ruby
 # setting an HTTP Header
-get articles_url, headers: "Content-Type" => "text/plain" # simulate the request with custom header
+get articles_url, headers: { "Content-Type": "text/plain" } # simulate the request with custom header
 
 # setting a CGI variable
-get articles_url, headers: "HTTP_REFERER" => "http://example.com/home" # simulate the request with custom env variable
+get articles_url, headers: { "HTTP_REFERER": "http://example.com/home" } # simulate the request with custom env variable
 ```
 
 ### Testing `flash` notices
diff --git a/guides/w3c_validator.rb b/guides/w3c_validator.rb
index 71f044b9c4..e3bb964a60 100644
--- a/guides/w3c_validator.rb
+++ b/guides/w3c_validator.rb
@@ -21,8 +21,8 @@
 #
 #     Separate many using commas:
 #
-#       # validates only association_basics.html and migrations.html
-#       rake guides:validate ONLY=assoc,migrations
+#       # validates only association_basics.html and command_line.html
+#       rake guides:validate ONLY=assoc,command
 #
 # ---------------------------------------------------------------------------