18 files changed, 222 insertions, 131 deletions
diff --git a/guides/source/5_1_release_notes.md b/guides/source/5_1_release_notes.md
index fa92b9e5f8..80c9da6446 100644
--- a/guides/source/5_1_release_notes.md
+++ b/guides/source/5_1_release_notes.md
@@ -602,7 +602,7 @@ Please refer to the [Changelog][active-support] for detailed changes.
     ([Pull Request](https://github.com/rails/rails/pull/28157))
 
 *   Deprecated passing string to `:if` and `:unless` conditional options on `set_callback` and `skip_callback`.
-    ([Commit](https://github.com/rails/rails/commit/0952552)
+    ([Commit](https://github.com/rails/rails/commit/0952552))
 
 ### Notable changes
 
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 2c3f74c3e1..5fb8e300de 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -400,9 +400,9 @@ Rails.application.config.session_store :cookie_store, key: '_your_app_session',
 Rails sets up (for the CookieStore) a secret key used for signing the session data in `config/credentials.yml.enc`. This can be changed with `bin/rails credentials:edit`.
 
 ```ruby
-# amazon:
-#  access_key_id: 123
-#  secret_access_key: 345
+# aws:
+#   access_key_id: 123
+#   secret_access_key: 345
 
 # Used as the base secret for all MessageVerifiers in Rails, including the one protecting cookies.
 secret_key_base: 492f...
diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md
index 96ef9c4450..cb07781d1c 100644
--- a/guides/source/action_mailer_basics.md
+++ b/guides/source/action_mailer_basics.md
@@ -92,8 +92,8 @@ registered email address:
 class UserMailer < ApplicationMailer
   default from: 'notifications@example.com'
 
-  def welcome_email(user)
-    @user = user
+  def welcome_email
+    @user = params[:user]
     @url  = 'http://example.com/login'
     mail(to: @user.email, subject: 'Welcome to My Awesome Site')
   end
@@ -176,7 +176,7 @@ $ bin/rails db:migrate
 Now that we have a user model to play with, we will just edit the
 `app/controllers/users_controller.rb` make it instruct the `UserMailer` to deliver
 an email to the newly created user by editing the create action and inserting a
-call to `UserMailer.welcome_email` right after the user is successfully saved.
+call to `UserMailer.with(user: @user).welcome_email` right after the user is successfully saved.
 
 Action Mailer is nicely integrated with Active Job so you can send emails outside
 of the request-response cycle, so the user doesn't have to wait on it:
@@ -191,7 +191,7 @@ class UsersController < ApplicationController
     respond_to do |format|
       if @user.save
         # Tell the UserMailer to send a welcome email after save
-        UserMailer.welcome_email(@user).deliver_later
+        UserMailer.with(user: @user).welcome_email.deliver_later
 
         format.html { redirect_to(@user, notice: 'User was successfully created.') }
         format.json { render json: @user, status: :created, location: @user }
@@ -220,12 +220,17 @@ If you want to send emails right away (from a cronjob for example) just call
 class SendWeeklySummary
   def run
     User.find_each do |user|
-      UserMailer.weekly_summary(user).deliver_now
+      UserMailer.with(user: user).weekly_summary.deliver_now
     end
   end
 end
 ```
 
+Any key value pair passed to `with` just becomes the `params` for the mailer
+action. So `with(user: @user, account: @user.account)` makes `params[:user]` and
+`params[:account]` available in the mailer action. Just like controllers have
+params.
+
 The method `welcome_email` returns an `ActionMailer::MessageDelivery` object which
 can then just be told `deliver_now` or `deliver_later` to send itself out. The
 `ActionMailer::MessageDelivery` object is just a wrapper around a `Mail::Message`. If
@@ -331,7 +336,7 @@ with the addresses separated by commas.
 
 ```ruby
 class AdminMailer < ApplicationMailer
-  default to: Proc.new { Admin.pluck(:email) },
+  default to: -> { Admin.pluck(:email) },
           from: 'notification@example.com'
 
   def new_registration(user)
@@ -351,8 +356,8 @@ address when they receive the email. The trick to doing that is to format the
 email address in the format `"Full Name" <email>`.
 
 ```ruby
-def welcome_email(user)
-  @user = user
+def welcome_email
+  @user = params[:user]
   email_with_name = %("#{@user.name}" <#{@user.email}>)
   mail(to: email_with_name, subject: 'Welcome to My Awesome Site')
 end
@@ -372,8 +377,8 @@ To change the default mailer view for your action you do something like:
 class UserMailer < ApplicationMailer
   default from: 'notifications@example.com'
 
-  def welcome_email(user)
-    @user = user
+  def welcome_email
+    @user = params[:user]
     @url  = 'http://example.com/login'
     mail(to: @user.email,
          subject: 'Welcome to My Awesome Site',
@@ -394,8 +399,8 @@ templates or even render inline or text without using a template file:
 class UserMailer < ApplicationMailer
   default from: 'notifications@example.com'
 
-  def welcome_email(user)
-    @user = user
+  def welcome_email
+    @user = params[:user]
     @url  = 'http://example.com/login'
     mail(to: @user.email,
          subject: 'Welcome to My Awesome Site') do |format|
@@ -453,8 +458,8 @@ the format block to specify different layouts for different formats:
 
 ```ruby
 class UserMailer < ApplicationMailer
-  def welcome_email(user)
-    mail(to: user.email) do |format|
+  def welcome_email
+    mail(to: params[:user].email) do |format|
       format.html { render layout: 'my_layout' }
       format.text
     end
@@ -477,7 +482,7 @@ special URL that renders them. In the above example, the preview class for
 ```ruby
 class UserMailerPreview < ActionMailer::Preview
   def welcome_email
-    UserMailer.welcome_email(User.first)
+    UserMailer.with(user: User.first).welcome_email
   end
 end
 ```
@@ -594,12 +599,12 @@ mailer action.
 
 ```ruby
 class UserMailer < ApplicationMailer
-  def welcome_email(user, company)
-    @user = user
+  def welcome_email
+    @user = params[:user]
     @url  = user_url(@user)
-    delivery_options = { user_name: company.smtp_user,
-                         password: company.smtp_password,
-                         address: company.smtp_host }
+    delivery_options = { user_name: params[:company].smtp_user,
+                         password: params[:company].smtp_password,
+                         address: params[:company].smtp_host }
     mail(to: @user.email,
          subject: "Please see the Terms and Conditions attached",
          delivery_method_options: delivery_options)
@@ -616,9 +621,9 @@ will default to `text/plain` otherwise.
 
 ```ruby
 class UserMailer < ApplicationMailer
-  def welcome_email(user, email_body)
-    mail(to: user.email,
-         body: email_body,
+  def welcome_email
+    mail(to: params[:user].email,
+         body: params[:email_body],
          content_type: "text/html",
          subject: "Already rendered!")
   end
@@ -677,24 +682,43 @@ Action Mailer allows for you to specify a `before_action`, `after_action` and
 * You could use a `before_action` to populate the mail object with defaults,
   delivery_method_options or insert default headers and attachments.
 
+```ruby
+class InvitationsMailer < ApplicationMailer
+  before_action { @inviter, @invitee = params[:inviter], params[:invitee] }
+  before_action { @account = params[:inviter].account }
+
+  default to:       -> { @invitee.email_address },
+          from:     -> { common_address(@inviter) },
+          reply_to: -> { @inviter.email_address_with_name }
+
+  def account_invitation
+    mail subject: "#{@inviter.name} invited you to their Basecamp (#{@account.name})"
+  end
+
+  def project_invitation
+    @project    = params[:project]
+    @summarizer = ProjectInvitationSummarizer.new(@project.bucket)
+
+    mail subject: "#{@inviter.name.familiar} added you to a project in Basecamp (#{@account.name})"
+  end
+end
+```
+
 * You could use an `after_action` to do similar setup as a `before_action` but
   using instance variables set in your mailer action.
 
 ```ruby
 class UserMailer < ApplicationMailer
+  before_action { @business, @user = params[:business], params[:user] }
+
   after_action :set_delivery_options,
                :prevent_delivery_to_guests,
                :set_business_headers
 
-  def feedback_message(business, user)
-    @business = business
-    @user = user
-    mail
+  def feedback_message
   end
 
-  def campaign_message(business, user)
-    @business = business
-    @user = user
+  def campaign_message
   end
 
   private
diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md
index 7a3ff12b63..914ef2c327 100644
--- a/guides/source/active_job_basics.md
+++ b/guides/source/active_job_basics.md
@@ -389,6 +389,25 @@ class GuestsCleanupJob < ApplicationJob
 end
 ```
 
+### Retrying or Discarding failed jobs
+
+It's also possible to retry or discard a job if an exception is raised during execution.
+For example:
+
+```ruby
+class RemoteServiceJob < ApplicationJob
+  retry_on CustomAppException # defaults to 3s wait, 5 attempts
+
+  discard_on ActiveJob::DeserializationError
+
+  def perform(*args)
+    # Might raise CustomAppException or ActiveJob::DeserializationError
+  end
+end
+```
+
+To get more details see the API Documentation for [ActiveJob::Exceptions](http://api.rubyonrails.org/classes/ActiveJob/Exceptions/ClassMethods.html).
+
 ### Deserialization
 
 GlobalID allows serializing full Active Record objects passed to `#perform`.
diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md
index 1438245f9c..ae573cc77c 100644
--- a/guides/source/active_support_core_extensions.md
+++ b/guides/source/active_support_core_extensions.md
@@ -674,44 +674,6 @@ M.parents       # => [X::Y, X, Object]
 
 NOTE: Defined in `active_support/core_ext/module/introspection.rb`.
 
-### Reachable
-
-A named module is reachable if it is stored in its corresponding constant. It means you can reach the module object via the constant.
-
-That is what ordinarily happens, if a module is called "M", the `M` constant exists and holds it:
-
-```ruby
-module M
-end
-
-M.reachable? # => true
-```
-
-But since constants and modules are indeed kind of decoupled, module objects can become unreachable:
-
-```ruby
-module M
-end
-
-orphan = Object.send(:remove_const, :M)
-
-# The module object is orphan now but it still has a name.
-orphan.name # => "M"
-
-# You cannot reach it via the constant M because it does not even exist.
-orphan.reachable? # => false
-
-# Let's define a module called "M" again.
-module M
-end
-
-# The constant M exists now again, and it stores a module
-# object called "M", but it is a new instance.
-orphan.reachable? # => false
-```
-
-NOTE: Defined in `active_support/core_ext/module/reachable.rb`.
-
 ### Anonymous
 
 A module may or may not have a name:
@@ -745,7 +707,6 @@ end
 
 m = Object.send(:remove_const, :M)
 
-m.reachable? # => false
 m.anonymous? # => false
 ```
 
diff --git a/guides/source/active_support_instrumentation.md b/guides/source/active_support_instrumentation.md
index 03c9183eb3..ff4288a7f5 100644
--- a/guides/source/active_support_instrumentation.md
+++ b/guides/source/active_support_instrumentation.md
@@ -304,7 +304,7 @@ Action Mailer
   mailer: "Notification",
   message_id: "4f5b5491f1774_181b23fc3d4434d38138e5@mba.local.mail",
   subject: "Rails Guides",
-  to: ["users@rails.com", "ddh@rails.com"],
+  to: ["users@rails.com", "dhh@rails.com"],
   from: ["me@rails.com"],
   date: Sat, 10 Mar 2012 14:18:09 +0100,
   mail: "..." # omitted for brevity
@@ -330,7 +330,7 @@ Action Mailer
   mailer: "Notification",
   message_id: "4f5b5491f1774_181b23fc3d4434d38138e5@mba.local.mail",
   subject: "Rails Guides",
-  to: ["users@rails.com", "ddh@rails.com"],
+  to: ["users@rails.com", "dhh@rails.com"],
   from: ["me@rails.com"],
   date: Sat, 10 Mar 2012 14:18:09 +0100,
   mail: "..." # omitted for brevity
diff --git a/guides/source/api_app.md b/guides/source/api_app.md
index da1b7b25ef..43a7de88b0 100644
--- a/guides/source/api_app.md
+++ b/guides/source/api_app.md
@@ -216,7 +216,6 @@ An API application comes with the following middleware by default:
 - `Rack::Head`
 - `Rack::ConditionalGet`
 - `Rack::ETag`
-- `MyApi::Application::Routes`
 
 See the [internal middleware](rails_on_rack.html#internal-middleware-stack)
 section of the Rack guide for further information on them.
diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md
index 17ab9c7600..8bd1f91304 100644
--- a/guides/source/asset_pipeline.md
+++ b/guides/source/asset_pipeline.md
@@ -154,7 +154,7 @@ environments. You can enable or disable it in your configuration through the
 
 More reading:
 
-* [Optimize caching](http://code.google.com/speed/page-speed/docs/caching.html)
+* [Optimize caching](https://developers.google.com/speed/docs/insights/LeverageBrowserCaching)
 * [Revving Filenames: don't use querystring](http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/)
 
 
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index b5bd24d027..9616647f15 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -906,7 +906,7 @@ The `belongs_to` association supports these options:
 
 ##### `:autosave`
 
-If you set the `:autosave` option to `true`, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object.
+If you set the `:autosave` option to `true`, Rails will save any loaded association members and destroy members that are marked for destruction whenever you save the parent object. Setting `:autosave` to `false` is not the same as not setting the `:autosave` option. If the `:autosave` option is not present, then new associated objects will be saved, but updated associated objects will not be saved.
 
 ##### `:class_name`
 
@@ -1257,7 +1257,7 @@ Setting the `:as` option indicates that this is a polymorphic association. Polym
 
 ##### `:autosave`
 
-If you set the `:autosave` option to `true`, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object.
+If you set the `:autosave` option to `true`, Rails will save any loaded association members and destroy members that are marked for destruction whenever you save the parent object. Setting `:autosave` to `false` is not the same as not setting the `:autosave` option. If the `:autosave` option is not present, then new associated objects will be saved, but updated associated objects will not be saved.
 
 ##### `:class_name`
 
@@ -1653,7 +1653,7 @@ Setting the `:as` option indicates that this is a polymorphic association, as di
 
 ##### `:autosave`
 
-If you set the `:autosave` option to `true`, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object.
+If you set the `:autosave` option to `true`, Rails will save any loaded association members and destroy members that are marked for destruction whenever you save the parent object. Setting `:autosave` to `false` is not the same as not setting the `:autosave` option. If the `:autosave` option is not present, then new associated objects will be saved, but updated associated objects will not be saved.
 
 ##### `:class_name`
 
@@ -2176,7 +2176,7 @@ end
 
 ##### `:autosave`
 
-If you set the `:autosave` option to `true`, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object.
+If you set the `:autosave` option to `true`, Rails will save any loaded association members and destroy members that are marked for destruction whenever you save the parent object. Setting `:autosave` to `false` is not the same as not setting the `:autosave` option. If the `:autosave` option is not present, then new associated objects will be saved, but updated associated objects will not be saved.
 
 ##### `:class_name`
 
diff --git a/guides/source/autoloading_and_reloading_constants.md b/guides/source/autoloading_and_reloading_constants.md
index c62194faf4..ede0324a51 100644
--- a/guides/source/autoloading_and_reloading_constants.md
+++ b/guides/source/autoloading_and_reloading_constants.md
@@ -954,7 +954,7 @@ to work on some subclass, things get interesting.
 While working with `Polygon` you do not need to be aware of all its descendants,
 because anything in the table is by definition a polygon, but when working with
 subclasses Active Record needs to be able to enumerate the types it is looking
-for. Let’s see an example.
+for. Let's see an example.
 
 `Rectangle.all` only loads rectangles by adding a type constraint to the query:
 
@@ -963,7 +963,7 @@ SELECT "polygons".* FROM "polygons"
 WHERE "polygons"."type" IN ("Rectangle")
 ```
 
-Let’s introduce now a subclass of `Rectangle`:
+Let's introduce now a subclass of `Rectangle`:
 
 ```ruby
 # app/models/square.rb
@@ -978,7 +978,7 @@ SELECT "polygons".* FROM "polygons"
 WHERE "polygons"."type" IN ("Rectangle", "Square")
 ```
 
-But there’s a caveat here: How does Active Record know that the class `Square`
+But there's a caveat here: How does Active Record know that the class `Square`
 exists at all?
 
 Even if the file `app/models/square.rb` exists and defines the `Square` class,
@@ -1049,7 +1049,7 @@ end
 
 The purpose of this setup would be that the application uses the class that
 corresponds to the environment via `AUTH_SERVICE`. In development mode
-`MockedAuthService` gets autoloaded when the initializer runs. Let’s suppose
+`MockedAuthService` gets autoloaded when the initializer runs. Let's suppose
 we do some requests, change its implementation, and hit the application again.
 To our surprise the changes are not reflected. Why?
 
diff --git a/guides/source/caching_with_rails.md b/guides/source/caching_with_rails.md
index 910a531068..96650b5be9 100644
--- a/guides/source/caching_with_rails.md
+++ b/guides/source/caching_with_rails.md
@@ -181,7 +181,7 @@ cache.
 
 ### Shared Partial Caching
 
-It is possible to share partials and associated caching between files with different mime types. For example shared partial caching allows template writers to share a partial between HTML and Javascript files. When templates are collected in the template resolver file paths they only include the template language extension and not the mime type. Because of this templates can be used for multiple mime types. Both HTML and JavaScript requests will respond to the following code:
+It is possible to share partials and associated caching between files with different mime types. For example shared partial caching allows template writers to share a partial between HTML and JavaScript files. When templates are collected in the template resolver file paths they only include the template language extension and not the mime type. Because of this templates can be used for multiple mime types. Both HTML and JavaScript requests will respond to the following code:
 
 ```ruby
 render(partial: 'hotels/hotel', collection: @hotels, cached: true)
@@ -195,7 +195,7 @@ Another option is to include the full filename of the partial to render.
 render(partial: 'hotels/hotel.html.erb', collection: @hotels, cached: true)
 ```
 
-Will load a file named `hotels/hotel.html.erb` in any file mime type, for example you could include this partial in a Javascript file.
+Will load a file named `hotels/hotel.html.erb` in any file mime type, for example you could include this partial in a JavaScript file.
 
 ### Managing dependencies
 
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index 1c720ad82f..0f87d73d6e 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -487,6 +487,15 @@ Defaults to `'signed cookie'`.
   authenticated encrypted cookie salt. Defaults to `'authenticated encrypted
   cookie'`.
 
+* `config.action_dispatch.encrypted_cookie_cipher` sets the cipher to be
+  used for encrypted cookies. This defaults to `"aes-256-gcm"`.
+
+* `config.action_dispatch.signed_cookie_digest` sets the digest to be
+  used for signed cookies. This defaults to `"SHA1"`.
+
+* `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)
   for more information. It defaults to `true`.
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md
index 7c7b3a4c01..70a945ad9e 100644
--- a/guides/source/getting_started.md
+++ b/guides/source/getting_started.md
@@ -594,7 +594,7 @@ familiar error:
 You now need to create the `create` action within the `ArticlesController` for
 this to work.
 
-NOTE: by default `form_with` submits forms using Ajax thereby skipping full page
+NOTE: By default `form_with` submits forms using Ajax thereby skipping full page
 redirects. To make this guide easier to get into we've disabled that with
 `local: true` for now.
 
diff --git a/guides/source/i18n.md b/guides/source/i18n.md
index cb24822f86..0153f52249 100644
--- a/guides/source/i18n.md
+++ b/guides/source/i18n.md
@@ -1187,7 +1187,7 @@ If you find your own locale (language) missing from our [example translations da
 Resources
 ---------
 
-* [Google group: rails-i18n](https://groups.google.com/forum/#!forum/rails-i18n) - The project's mailing list.
+* [Google group: rails-i18n](https://groups.google.com/group/rails-i18n) - The project's mailing list.
 * [GitHub: rails-i18n](https://github.com/svenfuchs/rails-i18n) - Code repository and issue tracker for the rails-i18n project. Most importantly you can find lots of [example translations](https://github.com/svenfuchs/rails-i18n/tree/master/rails/locale) for Rails that should work for your application in most cases.
 * [GitHub: i18n](https://github.com/svenfuchs/i18n) - Code repository and issue tracker for the i18n gem.
 
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
index 76b325d0bf..fe2477f2ae 100644
--- a/guides/source/layouts_and_rendering.md
+++ b/guides/source/layouts_and_rendering.md
@@ -71,23 +71,25 @@ If we want to display the properties of all the books in our view, we can do so
 <h1>Listing Books</h1>
 
 <table>
-  <tr>
-    <th>Title</th>
-    <th>Summary</th>
-    <th></th>
-    <th></th>
-    <th></th>
-  </tr>
-
-<% @books.each do |book| %>
-  <tr>
-    <td><%= book.title %></td>
-    <td><%= book.content %></td>
-    <td><%= link_to "Show", book %></td>
-    <td><%= link_to "Edit", edit_book_path(book) %></td>
-    <td><%= link_to "Remove", book, method: :delete, data: { confirm: "Are you sure?" } %></td>
-  </tr>
-<% end %>
+  <thead>
+    <tr>
+      <th>Title</th>
+      <th>Content</th>
+      <th colspan="3"></th>
+    </tr>
+  </thead>
+
+  <tbody>
+    <% @books.each do |book| %>
+      <tr>
+        <td><%= book.title %></td>
+        <td><%= book.content %></td>
+        <td><%= link_to "Show", book %></td>
+        <td><%= link_to "Edit", edit_book_path(book) %></td>
+        <td><%= link_to "Destroy", book, method: :delete, data: { confirm: "Are you sure?" } %></td>
+      </tr>
+    <% end %>
+  </tbody>
 </table>
 
 <br>
diff --git a/guides/source/plugins.md b/guides/source/plugins.md
index 0f0cde7634..b3a7f544f5 100644
--- a/guides/source/plugins.md
+++ b/guides/source/plugins.md
@@ -237,7 +237,7 @@ Finished in 0.004812s, 831.2949 runs/s, 415.6475 assertions/s.
 
 This tells us that we don't have the necessary models (Hickwall and Wickwall) that we are trying to test.
 We can easily generate these models in our "dummy" Rails application by running the following commands from the
-test/dummy directory:
+`test/dummy` directory:
 
 ```bash
 $ cd test/dummy
diff --git a/guides/source/security.md b/guides/source/security.md
index a74de22ac0..9e1dc518d2 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -85,37 +85,114 @@ This will also be a good idea, if you modify the structure of an object and old
 
 * _Critical data should not be stored in session_. If the user clears their cookies or closes the browser, they will be lost. And with a client-side session storage, the user can read the data.
 
-### Session Storage
+### Encrypted Session Storage
 
 NOTE: _Rails provides several storage mechanisms for the session hashes. The most important is `ActionDispatch::Session::CookieStore`._
 
-Rails 2 introduced a new default session storage, CookieStore. CookieStore saves the session hash directly in a cookie on the client-side. The server retrieves the session hash from the cookie and eliminates the need for a session ID. That will greatly increase the speed of the application, but it is a controversial storage option and you have to think about the security implications of it:
+The `CookieStore` saves the session hash directly in a cookie on the
+client-side. The server retrieves the session hash from the cookie and
+eliminates the need for a session ID. That will greatly increase the
+speed of the application, but it is a controversial storage option and
+you have to think about the security implications and storage
+limitations of it:
+
+* Cookies imply a strict size limit of 4kB. This is fine as you should
+  not store large amounts of data in a session anyway, as described
+  before. Storing the current user's database id in a session is common
+  practice.
+
+* Session cookies do not invalidate themselves and can be maliciously
+  reused. It may be a good idea to have your application invalidate old
+  session cookies using a stored timestamp.
+
+The `CookieStore` uses the
+[encrypted](http://api.rubyonrails.org/classes/ActionDispatch/Cookies/ChainedCookieJars.html#method-i-encrypted)
+cookie jar to provide a secure, encrypted location to store session
+data. Cookie-based sessions thus provide both integrity as well as
+confidentiality to their contents. The encryption key, as well as the
+verification key used for
+[signed](http://api.rubyonrails.org/classes/ActionDispatch/Cookies/ChainedCookieJars.html#method-i-signed)
+cookies, is derived from the `secret_key_base` configuration value.
+
+As of Rails 5.2 encrypted cookies and sessions are protected using AES
+GCM encryption. This form of encryption is a type of Authenticated
+Encryption and couples authentication and encryption in single step
+while also producing shorter ciphertexts as compared to other
+algorithms previously used. The key for cookies encrypted with AES GCM
+are derived using a salt value defined by the
+`config.action_dispatch.authenticated_encrypted_cookie_salt`
+configuration value.
+
+Prior to this version, encrypted cookies were secured using AES in CBC
+mode with HMAC using SHA1 for authentication. The keys for this type of
+encryption and for HMAC verification were derived via the salts defined
+by `config.action_dispatch.encrypted_cookie_salt` and
+`config.action_dispatch.encrypted_signed_cookie_salt` respectively.
+
+Prior to Rails version 4 in both versions 2 and 3, session cookies were
+protected using only HMAC verification. As such, these session cookies
+only provided integrity to their content because the actual session data
+was stored in plaintext encoded as base64. This is how `signed` cookies
+work in the current version of Rails. These kinds of cookies are still
+useful for protecting the integrity of certain client-stored data and
+information.
+
+__Do not use a trivial secret for the `secret_key_base`, i.e. a word
+from a dictionary, or one which is shorter than 30 characters! Instead
+use `rails secret` to generate secret keys!__
+
+It is also important to use different salt values for encrypted and
+signed cookies. Using the same value for different salt configuration
+values may lead to the same derived key being used for different
+security features which in turn may weaken the strength of the key.
 
-* Cookies imply a strict size limit of 4kB. This is fine as you should not store large amounts of data in a session anyway, as described before. _Storing the current user's database id in a session is usually ok_.
+In test and development applications get a `secret_key_base` derived from the app name. Other environments must use a random key present in `config/credentials.yml.enc`, shown here in its decrypted state:
 
-* The client can see everything you store in a session, because it is stored in clear-text (actually Base64-encoded, so not encrypted). So, of course, _you don't want to store any secrets here_. To prevent session hash tampering, a digest is calculated from the session with a server-side secret (`secrets.secret_token`) and inserted into the end of the cookie.
+    secret_key_base: 492f...
 
-In Rails 4, encrypted cookies through AES in CBC mode with HMAC using SHA1 for
-verification was introduced. This prevents the user from accessing and tampering
-the content of the cookie. Thus the session becomes a more secure place to store
-data. The encryption is performed using a server-side `secret_key_base`.
-Two salts are used when deriving keys for encryption and verification. These
-salts are set via the `config.action_dispatch.encrypted_cookie_salt` and
-`config.action_dispatch.encrypted_signed_cookie_salt` configuration values.
+If you have received an application where the secret was exposed (e.g. an application whose source was shared), strongly consider changing the secret.
 
-Rails 5.2 uses AES-GCM for the encryption which couples authentication
-and encryption in one faster step and produces shorter ciphertexts.
+### Rotating Keys for Encrypted and Signed Cookies
 
-Encrypted cookies are automatically upgraded if the
-`config.action_dispatch.use_authenticated_cookie_encryption` is enabled.
+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.
 
-_Do not use a trivial secret, i.e. a word from a dictionary, or one which is shorter than 30 characters! Instead use `rails secret` to generate secret keys!_
+For example to rotate out an old `secret_key_base`, we can define signed and
+encrypted rotations as follows:
 
-In test and development applications get a `secret_key_base` derived from the app name. Other environments must use a random key present in `config/credentials.yml.enc`, shown here in its decrypted state:
+```ruby
+Rails.application.config.action_dispatch.cookies_rotations.tap do |cookies|
+  cookies.rotate :encrypted, secret: Rails.application.credentials.old_secret_key_base
+  cookies.rotate :signed,    secret: Rails.application.credentials.old_secret_key_base
+end
+```
 
-    secret_key_base: 492f...
+It's also possible to set up multiple rotations. For instance to use `SHA512`
+for signed cookies while rotating out SHA256 and SHA1 digests, we'd do:
 
-If you have received an application where the secret was exposed (e.g. an application whose source was shared), strongly consider changing the secret.
+```ruby
+Rails.application.config.action_dispatch.signed_cookie_digest = "SHA512"
+
+Rails.application.config.action_dispatch.cookies_rotations.tap do |cookies|
+  cookies.rotate :signed, digest: "SHA256"
+  cookies.rotate :signed, digest: "SHA1"
+end
+```
+
+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
+the
+[MessageEncryptor API](api.rubyonrails.org/classes/ActiveSupport/MessageEncryptor.html)
+and
+[MessageVerifier API](api.rubyonrails.org/classes/ActiveSupport/MessageVerifier.html)
+documentation.
 
 ### Replay Attacks for CookieStore Sessions
 
@@ -1029,7 +1106,7 @@ Rails generates a `config/credentials.yml.enc` to store third-party credentials
 within the repo. This is only viable because Rails encrypts the file with a master
 key that's generated into a version control ignored `config/master.key` — Rails
 will also look for that key in `ENV["RAILS_MASTER_KEY"]`. Rails also requires the
-the key to boot in production, so the credentials can be read.
+key to boot in production, so the credentials can be read.
 
 To edit stored credentials use `bin/rails credentials:edit`.
 
@@ -1038,18 +1115,18 @@ By default, this file contains the application's
 access keys for external APIs.
 
 The credentials added to this file are accessible via `Rails.application.credentials`.
-For example, with the following decrypted `config/credentails.yml.enc`:
+For example, with the following decrypted `config/credentials.yml.enc`:
 
     secret_key_base: 3b7cd727ee24e8444053437c36cc66c3
     some_api_key: SOMEKEY
 
-`Rails.application.credentails.some_api_key` returns `SOMEKEY` in any environment.
+`Rails.application.credentials.some_api_key` returns `SOMEKEY` in any environment.
 
 If you want an exception to be raised when some key is blank, use the bang
 version:
 
 ```ruby
-Rails.application.credentails.some_api_key! # => raises KeyError: key not found: :some_api_key
+Rails.application.credentials.some_api_key! # => raises KeyError: :some_api_key is blank
 ```
 
 Additional Resources
diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md
index 27cef2bd27..098366ec1b 100644
--- a/guides/source/working_with_javascript_in_rails.md
+++ b/guides/source/working_with_javascript_in_rails.md
@@ -382,7 +382,7 @@ Rails 5.1 introduced rails-ujs and dropped jQuery as a dependency.
 As a result the Unobtrusive JavaScript (UJS) driver has been rewritten to operate without jQuery.
 These introductions cause small changes to `custom events` fired during the request:
 
-NOTE: Signature of calls to UJS’s event handlers has changed.
+NOTE: Signature of calls to UJS's event handlers has changed.
 Unlike the version with jQuery, all custom events return only one parameter: `event`.
 In this parameter, there is an additional attribute `detail` which contains an array of extra parameters.