19 files changed, 94 insertions, 55 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 bdd1c2cc4e..3710247582 100644
--- a/guides/source/5_0_release_notes.md
+++ b/guides/source/5_0_release_notes.md
@@ -90,9 +90,10 @@ It also changes the behavior of values passed to `ActiveRecord::Base.where`, whi
 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
 
@@ -130,8 +131,8 @@ model.attributes #=> {field_without_db_column: [1, 2, 3]}
 **Creating Custom Types:**
 
 You can define your own custom types, as long as they respond
-to the methods defined on the value type. The method +deserialize+ or
-+cast+ will be called on your type object, with raw input from the
+to the methods defined on the value type. The method `deserialize` or
+`cast` will be called on your type object, with raw input from the
 database or from your controllers. This is useful, for example, when doing custom conversion,
 like Money data.
 
@@ -139,7 +140,7 @@ like Money data.
 
 When `ActiveRecord::Base.where` is called, it will
 use the type defined by the model class to convert the value to SQL,
-calling +serialize+ on your type object.
+calling `serialize` on your type object.
 
 This gives the objects ability to specify, how to convert values when performing SQL queries.
 
@@ -205,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/action_cable_overview.md b/guides/source/action_cable_overview.md
index 2308befd12..0d00b7f07b 100644
--- a/guides/source/action_cable_overview.md
+++ b/guides/source/action_cable_overview.md
@@ -9,7 +9,9 @@ After reading this guide, you will know:
 * What Action Cable is and its integration on backend and frontend  
 * How to setup Action Cable
 * How to setup channels
-* Deployment and Architecture setup for running Action Cable 
+* Deployment and Architecture setup for running Action Cable
+
+--------------------------------------------------------------------------------
 
 Introduction
 ------------
diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md
index 7359438025..34847832fd 100644
--- a/guides/source/action_mailer_basics.md
+++ b/guides/source/action_mailer_basics.md
@@ -735,7 +735,7 @@ files (environment.rb, production.rb, etc...)
 |---------------|-------------|
 |`logger`|Generates information on the mailing run if available. Can be set to `nil` for no logging. Compatible with both Ruby's own `Logger` and `Log4r` loggers.|
 |`smtp_settings`|Allows detailed configuration for `:smtp` delivery method:<ul><li>`:address` - Allows you to use a remote mail server. Just change it from its default `"localhost"` setting.</li><li>`:port` - On the off chance that your mail server doesn't run on port 25, you can change it.</li><li>`:domain` - If you need to specify a HELO domain, you can do it here.</li><li>`:user_name` - If your mail server requires authentication, set the username in this setting.</li><li>`:password` - If your mail server requires authentication, set the password in this setting.</li><li>`:authentication` - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of `:plain` (will send the password in the clear), `:login` (will send password Base64 encoded) or `:cram_md5` (combines a Challenge/Response mechanism to exchange information and a cryptographic Message Digest 5 algorithm to hash important information)</li><li>`:enable_starttls_auto` - Detects if STARTTLS is enabled in your SMTP server and starts to use it. Defaults to `true`.</li><li>`:openssl_verify_mode` - When using TLS, you can set how OpenSSL checks the certificate. This is really useful if you need to validate a self-signed and/or a wildcard certificate. You can use the name of an OpenSSL verify constant ('none' or 'peer') or directly the constant (`OpenSSL::SSL::VERIFY_NONE` or `OpenSSL::SSL::VERIFY_PEER`).</li></ul>|
-|`sendmail_settings`|Allows you to override options for the `:sendmail` delivery method.<ul><li>`:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`.</li><li>`:arguments` - The command line arguments to be passed to sendmail. Defaults to `-i -t`.</li></ul>|
+|`sendmail_settings`|Allows you to override options for the `:sendmail` delivery method.<ul><li>`:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`.</li><li>`:arguments` - The command line arguments to be passed to sendmail. Defaults to `-i`.</li></ul>|
 |`raise_delivery_errors`|Whether or not errors should be raised if the email fails to be delivered. This only works if the external email server is configured for immediate delivery.|
 |`delivery_method`|Defines a delivery method. Possible values are:<ul><li>`:smtp` (default), can be configured by using `config.action_mailer.smtp_settings`.</li><li>`:sendmail`, can be configured by using `config.action_mailer.sendmail_settings`.</li><li>`:file`: save emails to files; can be configured by using `config.action_mailer.file_settings`.</li><li>`:test`: save emails to `ActionMailer::Base.deliveries` array.</li></ul>See [API docs](http://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.|
 |`perform_deliveries`|Determines whether deliveries are actually carried out when the `deliver` method is invoked on the Mail message. By default they are, but this can be turned off to help functional testing.|
@@ -756,7 +756,7 @@ config.action_mailer.delivery_method = :sendmail
 # Defaults to:
 # config.action_mailer.sendmail_settings = {
 #   location: '/usr/sbin/sendmail',
-#   arguments: '-i -t'
+#   arguments: '-i'
 # }
 config.action_mailer.perform_deliveries = true
 config.action_mailer.raise_delivery_errors = true
diff --git a/guides/source/action_view_overview.md b/guides/source/action_view_overview.md
index f68abbae3c..e11466e79f 100644
--- a/guides/source/action_view_overview.md
+++ b/guides/source/action_view_overview.md
@@ -1439,7 +1439,7 @@ Formats a number with the specified level of `precision`, which defaults to 3.
 
 ```ruby
 number_with_precision(111.2345)     # => 111.235
-number_with_precision(111.2345, 2)  # => 111.23
+number_with_precision(111.2345, precision: 2)  # => 111.23
 ```
 
 ### SanitizeHelper
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 59cf412c5f..34878e5c38 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -297,7 +297,9 @@ 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] }
     ```
 
 ### Configuring Active Record
@@ -531,7 +533,7 @@ There are a number of settings available on `config.action_mailer`:
 
 * `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`.
-    * `:arguments` - The command line arguments. Defaults to `-i -t`.
+    * `:arguments` - The command line arguments. Defaults to `-i`.
 
 * `config.action_mailer.raise_delivery_errors` specifies whether to raise an error if email delivery cannot be completed. It defaults to `true`.
 
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/initialization.md b/guides/source/initialization.md
index 89e5346d86..a2eec03eba 100644
--- a/guides/source/initialization.md
+++ b/guides/source/initialization.md
@@ -16,7 +16,7 @@ After reading this guide, you will know:
 --------------------------------------------------------------------------------
 
 This guide goes through every method call that is
-required to boot up the Ruby on Rails stack for a default Rails 4
+required to boot up the Ruby on Rails stack for a default Rails
 application, explaining each part in detail along the way. For this
 guide, we will be focusing on what happens when you execute `rails server`
 to boot your app.
@@ -464,7 +464,7 @@ The `options[:config]` value defaults to `config.ru` which contains this:
 ```ruby
 # This file is used by Rack-based servers to start the application.
 
-require ::File.expand_path('../config/environment', __FILE__)
+require_relative 'config/environment'
 run <%= app_const %>
 ```
 
@@ -485,7 +485,7 @@ end
 The `initialize` method of `Rack::Builder` will take the block here and execute it within an instance of `Rack::Builder`. This is where the majority of the initialization process of Rails happens. The `require` line for `config/environment.rb` in `config.ru` is the first to run:
 
 ```ruby
-require ::File.expand_path('../config/environment', __FILE__)
+require_relative 'config/environment'
 ```
 
 ### `config/environment.rb`
@@ -495,7 +495,7 @@ This file is the common file required by `config.ru` (`rails server`) and Passen
 This file begins with requiring `config/application.rb`:
 
 ```ruby
-require File.expand_path('../application', __FILE__)
+require_relative 'application'
 ```
 
 ### `config/application.rb`
@@ -503,7 +503,7 @@ require File.expand_path('../application', __FILE__)
 This file requires `config/boot.rb`:
 
 ```ruby
-require File.expand_path('../boot', __FILE__)
+require_relative 'boot'
 ```
 
 But only if it hasn't been required before, which would be the case in `rails server`
diff --git a/guides/source/layout.html.erb b/guides/source/layout.html.erb
index 9abb863da6..943fd3fd7f 100644
--- a/guides/source/layout.html.erb
+++ b/guides/source/layout.html.erb
@@ -127,13 +127,11 @@
   <script type="text/javascript" src="javascripts/jquery.min.js"></script>
   <script type="text/javascript" src="javascripts/responsive-tables.js"></script>
   <script type="text/javascript" src="javascripts/guides.js"></script>
-  <script type="text/javascript" src="javascripts/syntaxhighlighter/shCore.js"></script>
-  <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushRuby.js"></script>
-  <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushXml.js"></script>
-  <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushSql.js"></script>
-  <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushPlain.js"></script>
+  <script type="text/javascript" src="javascripts/syntaxhighlighter.js"></script>
   <script type="text/javascript">
-    SyntaxHighlighter.all();
+    syntaxhighlighterConfig = {
+      autoLinks: false,
+    };
     $(guidesIndex.bind);
   </script>
 </body>
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/rails_on_rack.md b/guides/source/rails_on_rack.md
index 8148f70c31..ed935e1008 100644
--- a/guides/source/rails_on_rack.md
+++ b/guides/source/rails_on_rack.md
@@ -64,7 +64,7 @@ To use `rackup` instead of Rails' `rails server`, you can put the following insi
 
 ```ruby
 # Rails.root/config.ru
-require ::File.expand_path('../config/environment', __FILE__)
+require_relative 'config/environment'
 run Rails.application
 ```
 
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 e8dc6ffe2a..26d50bec0c 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -851,12 +851,25 @@ cookies["are_good_for_u"]     cookies[:are_good_for_u]
 
 ### Instance Variables Available
 
-You also have access to three instance variables in your functional tests:
+You also have access to three instance variables in your functional tests, after a request is made:
 
 * `@controller` - The controller processing the request
 * `@request` - The request object
 * `@response` - The response object
 
+
+```ruby
+class ArticlesControllerTest < ActionDispatch::IntegrationTest
+  test "should get index" do
+    get articles_url
+        
+    assert_equal "index",  @controller.action_name
+    assert_equal "application/x-www-form-urlencoded",  @request.media_type
+    assert_match "Articles", @response.body    
+  end
+end
+```
+
 ### Setting Headers and CGI variables
 
 [HTTP headers](http://tools.ietf.org/search/rfc2616#section-5.3)
@@ -866,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/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index c41876cd28..2ac5a2188b 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -1185,7 +1185,7 @@ Please read [Pull Request #9978](https://github.com/rails/rails/pull/9978) for d
 
 * Rails 4.0 has deprecated `ActionController::Base.page_cache_extension` option. Use `ActionController::Base.default_static_extension` instead.
 
-* Rails 4.0 has removed Action and Page caching from Action Pack. You will need to add the `actionpack-action_caching` gem in order to use `caches_action` and the `actionpack-page_caching` to use `caches_pages` in your controllers.
+* Rails 4.0 has removed Action and Page caching from Action Pack. You will need to add the `actionpack-action_caching` gem in order to use `caches_action` and the `actionpack-page_caching` to use `caches_page` in your controllers.
 
 * Rails 4.0 has removed the XML parameters parser. You will need to add the `actionpack-xml_parser` gem if you require this feature.