6 files changed, 42 insertions, 53 deletions
diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index 678b80516f..3573c3c77b 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -414,7 +414,7 @@ end
 `find_in_batches` works on model classes, as seen above, and also on relations:
 
 ```ruby
-Invoice.pending.find_in_batches do |invoice|
+Invoice.pending.find_in_batches do |invoices|
   pending_invoices_export.add_invoices(invoices)
 end
 ```
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index 86c8364d83..0f87d73d6e 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -493,10 +493,8 @@ Defaults to `'signed cookie'`.
 * `config.action_dispatch.signed_cookie_digest` sets the digest to be
   used for signed cookies. This defaults to `"SHA1"`.
 
-* `config.action_dispatch.cookies_rotations` is set to an instance of
-  [RotationConfiguration](http://api.rubyonrails.org/classes/ActiveSupport/RotationConfiguration.html).
-  It provides an interface for rotating keys, salts, ciphers, and
-  digests for encrypted and signed cookies.
+* `config.action_dispatch.cookies_rotations` allows rotating
+  secrets, ciphers, and digests for encrypted and signed cookies.
 
 * `config.action_dispatch.perform_deep_munge` configures whether `deep_munge`
   method should be performed on the parameters. See [Security Guide](security.html#unsafe-query-generation)
diff --git a/guides/source/engines.md b/guides/source/engines.md
index c7331b6ca4..188620a683 100644
--- a/guides/source/engines.md
+++ b/guides/source/engines.md
@@ -63,7 +63,7 @@ authentication for its parent applications, or
 [Thredded](https://github.com/thredded/thredded), an engine that provides forum
 functionality. There's also [Spree](https://github.com/spree/spree) which
 provides an e-commerce platform, and
-[RefineryCMS](https://github.com/refinery/refinerycms), a CMS engine.
+[Refinery CMS](https://github.com/refinery/refinerycms), a CMS engine.
 
 Finally, engines would not have been possible without the work of James Adam,
 Piotr Sarnacki, the Rails Core Team, and a number of other people. If you ever
@@ -1322,7 +1322,7 @@ engine.
 
 Assets within an engine work in an identical way to a full application. Because
 the engine class inherits from `Rails::Engine`, the application will know to
-look up assets in the engine's 'app/assets' and 'lib/assets' directories.
+look up assets in the engine's `app/assets` and `lib/assets` directories.
 
 Like all of the other components of an engine, the assets should be namespaced.
 This means that if you have an asset called `style.css`, it should be placed at
diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md
index f46f1648b3..4ce67df93a 100644
--- a/guides/source/form_helpers.md
+++ b/guides/source/form_helpers.md
@@ -274,10 +274,12 @@ There are a few things to note here:
 The resulting HTML is:
 
 ```html
-<form accept-charset="UTF-8" action="/articles" method="post" class="nifty_form">
-  <input id="article_title" name="article[title]" type="text" />
-  <textarea id="article_body" name="article[body]" cols="60" rows="12"></textarea>
-  <input name="commit" type="submit" value="Create" />
+<form class="nifty_form" id="new_article" action="/articles" accept-charset="UTF-8" method="post">
+  <input name="utf8" type="hidden" value="&#x2713;" />
+  <input type="hidden" name="authenticity_token" value="NRkFyRWxdYNfUg7vYxLOp2SLf93lvnl+QwDWorR42Dp6yZXPhHEb6arhDOIWcqGit8jfnrPwL781/xlrzj63TA==" />
+  <input type="text" name="article[title]" id="article_title" />
+  <textarea name="article[body]" id="article_body" cols="60" rows="12"></textarea>
+  <input type="submit" name="commit" value="Create" data-disable-with="Create" />
 </form>
 ```
 
@@ -299,9 +301,11 @@ You can create a similar binding without actually creating `<form>` tags with th
 which produces the following output:
 
 ```html
-<form accept-charset="UTF-8" action="/people" class="new_person" id="new_person" method="post">
-  <input id="person_name" name="person[name]" type="text" />
-  <input id="contact_detail_phone_number" name="contact_detail[phone_number]" type="text" />
+<form class="new_person" id="new_person" action="/people" accept-charset="UTF-8" method="post">
+  <input name="utf8" type="hidden" value="&#x2713;" />
+  <input type="hidden" name="authenticity_token" value="bL13x72pldyDD8bgtkjKQakJCpd4A8JdXGbfksxBDHdf1uC0kCMqe2tvVdUYfidJt0fj3ihC4NxiVHv8GVYxJA==" />
+  <input type="text" name="person[name]" id="person_name" />
+  <input type="text" name="contact_detail[phone_number]" id="contact_detail_phone_number" />
 </form>
 ```
 
diff --git a/guides/source/plugins.md b/guides/source/plugins.md
index b3a7f544f5..5048444cb2 100644
--- a/guides/source/plugins.md
+++ b/guides/source/plugins.md
@@ -359,7 +359,7 @@ When you run `bin/test`, you should see the tests all pass:
 
 ### Add an Instance Method
 
-This plugin will add a method named 'squawk' to any Active Record object that calls 'acts_as_yaffle'. The 'squawk'
+This plugin will add a method named 'squawk' to any Active Record object that calls `acts_as_yaffle`. The 'squawk'
 method will simply set the value of one of the fields in the database.
 
 To start out, write a failing test that shows the behavior you'd like:
@@ -392,7 +392,7 @@ end
 ```
 
 Run the test to make sure the last two tests fail with an error that contains "NoMethodError: undefined method `squawk'",
-then update 'acts_as_yaffle.rb' to look like this:
+then update `acts_as_yaffle.rb` to look like this:
 
 ```ruby
 # yaffle/lib/yaffle/acts_as_yaffle.rb
diff --git a/guides/source/security.md b/guides/source/security.md
index b0b71cad7d..a07d583f15 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -152,54 +152,41 @@ In test and development applications get a `secret_key_base` derived from the ap
 
 If you have received an application where the secret was exposed (e.g. an application whose source was shared), strongly consider changing the secret.
 
-### Rotating Keys for Encrypted and Signed Cookies
+### Rotating Encrypted and Signed Cookies Configurations
 
-It is possible to rotate the `secret_key_base` as well as the salts,
-ciphers, and digests used for both encrypted and signed cookies. Rotating
-the `secret_key_base` is necessary if the value was exposed or leaked.
-It is also useful to rotate this value for other more benign reasons,
-such as an employee leaving your organization or changing hosting
-environments.
+Rotation is ideal for changing cookie configurations and ensuring old cookies
+aren't immediately invalid. Your users then have a chance to visit your site,
+get their cookie read with an old configuration and have it rewritten with the
+new change. The rotation can then be removed once you're comfortable enough
+users have had their chance to get their cookies upgraded.
 
-Key rotations can be defined through the
-`config.action_dispatch.cookies_rotations` configuration value. This
-value is set to an instance of
-[RotationConfiguration](http://api.rubyonrails.org/classes/ActiveSupport/RotationConfiguration.html)
-which provides an interface for rotating signed and encrypted cookie
-keys, salts, digests, and ciphers.
+It's possible to rotate the ciphers and digests used for encrypted and signed cookies.
 
-For example, suppose we want to rotate out an old `secret_key_base`, we
-can define a signed and encrypted key rotation as follows:
+For instance to change the digest used for signed cookies from SHA1 to SHA256,
+you would first assign the new configuration value:
 
 ```ruby
-config.action_dispatch.cookies_rotations.rotate :encrypted,
-  cipher: "aes-256-gcm",
-  secret: Rails.application.credentials.old_secret_key_base,
-  salt: config.action_dispatch.authenticated_encrypted_cookie_salt
-
-config.action_dispatch.cookies_rotations.rotate :signed,
-  digest: "SHA1",
-  secret: Rails.application.credentials.old_secret_key_base,
-  salt: config.action_dispatch.signed_cookie_salt
+Rails.application.config.action_dispatch.signed_cookie_digest = "SHA256"
 ```
 
-Multiple rotations are possible by calling `rotate` multiple times. For
-example, suppose we want to use SHA512 for signed cookies while rotating
-out SHA256 and SHA1 digests using the same `secret_key_base`
+Then you'd set up a rotation with the old configuration to keep it alive.
 
 ```ruby
-config.action_dispatch.signed_cookie_digest = "SHA512"
+Rails.application.config.action_dispatch.cookies_rotations.tap do |cookies|
+  cookies.rotate :signed, digest: "SHA256"
+end
+```
 
-config.action_dispatch.cookies_rotations.rotate :signed,
-  digest: "SHA256",
-  secret: Rails.application.credentials.secret_key_base,
-  salt: config.action_dispatch.signed_cookie_salt
+Then any written signed cookies will be digested with SHA256. Old cookies
+that were written with SHA1 can still be read, and if accessed will be written
+with the new digest so they're upgraded and won't be invalid when you remove the
+rotation.
 
-config.action_dispatch.cookies_rotations.rotate :signed,
-  digest: "SHA1",
-  secret: Rails.application.credentials.secret_key_base,
-  salt: config.action_dispatch.signed_cookie_salt
-```
+Once users with SHA1 digested signed cookies should no longer have a chance to
+have their cookies rewritten, remove the rotation.
+
+While you can setup as many rotations as you'd like it's not common to have many
+rotations going at any one time.
 
 For more details on key rotation with encrypted and signed messages as
 well as the various options the `rotate` method accepts, please refer to