14 files changed, 55 insertions, 22 deletions
diff --git a/guides/bug_report_templates/action_controller_gem.rb b/guides/bug_report_templates/action_controller_gem.rb
index 4d8d8db3e5..557b1d7bef 100644
--- a/guides/bug_report_templates/action_controller_gem.rb
+++ b/guides/bug_report_templates/action_controller_gem.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   # Activate the gem you are reporting the issue against.
   gem "rails", "5.1.0"
 end
@@ -19,7 +22,6 @@ require "action_controller/railtie"
 class TestApp < Rails::Application
   config.root = __dir__
   config.session_store :cookie_store, key: "cookie_store_key"
-  secrets.secret_token    = "secret_token"
   secrets.secret_key_base = "secret_key_base"
 
   config.logger = Logger.new($stdout)
diff --git a/guides/bug_report_templates/action_controller_master.rb b/guides/bug_report_templates/action_controller_master.rb
index 1f862e07da..cf76de80d2 100644
--- a/guides/bug_report_templates/action_controller_master.rb
+++ b/guides/bug_report_templates/action_controller_master.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   gem "rails", github: "rails/rails"
   gem "arel", github: "rails/arel"
 end
@@ -17,7 +20,6 @@ require "action_controller/railtie"
 
 class TestApp < Rails::Application
   config.root = __dir__
-  secrets.secret_token    = "secret_token"
   secrets.secret_key_base = "secret_key_base"
 
   config.logger = Logger.new($stdout)
diff --git a/guides/bug_report_templates/active_job_gem.rb b/guides/bug_report_templates/active_job_gem.rb
index af777a86ef..013d1f8602 100644
--- a/guides/bug_report_templates/active_job_gem.rb
+++ b/guides/bug_report_templates/active_job_gem.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   # Activate the gem you are reporting the issue against.
   gem "activejob", "5.1.0"
 end
diff --git a/guides/bug_report_templates/active_job_master.rb b/guides/bug_report_templates/active_job_master.rb
index 39fb3f60a6..ce480cbb52 100644
--- a/guides/bug_report_templates/active_job_master.rb
+++ b/guides/bug_report_templates/active_job_master.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   gem "rails", github: "rails/rails"
   gem "arel", github: "rails/arel"
 end
diff --git a/guides/bug_report_templates/active_record_gem.rb b/guides/bug_report_templates/active_record_gem.rb
index 168e2dcc66..921917fbe9 100644
--- a/guides/bug_report_templates/active_record_gem.rb
+++ b/guides/bug_report_templates/active_record_gem.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   # Activate the gem you are reporting the issue against.
   gem "activerecord", "5.1.0"
   gem "sqlite3"
diff --git a/guides/bug_report_templates/active_record_master.rb b/guides/bug_report_templates/active_record_master.rb
index cbd2cff2b8..78411e2d57 100644
--- a/guides/bug_report_templates/active_record_master.rb
+++ b/guides/bug_report_templates/active_record_master.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   gem "rails", github: "rails/rails"
   gem "arel", github: "rails/arel"
   gem "sqlite3"
diff --git a/guides/bug_report_templates/active_record_migrations_gem.rb b/guides/bug_report_templates/active_record_migrations_gem.rb
index b931ed0beb..f75b6fd932 100644
--- a/guides/bug_report_templates/active_record_migrations_gem.rb
+++ b/guides/bug_report_templates/active_record_migrations_gem.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   # Activate the gem you are reporting the issue against.
   gem "activerecord", "5.1.0"
   gem "sqlite3"
diff --git a/guides/bug_report_templates/active_record_migrations_master.rb b/guides/bug_report_templates/active_record_migrations_master.rb
index 2c009c0563..60416ed42f 100644
--- a/guides/bug_report_templates/active_record_migrations_master.rb
+++ b/guides/bug_report_templates/active_record_migrations_master.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   gem "rails", github: "rails/rails"
   gem "arel", github: "rails/arel"
   gem "sqlite3"
diff --git a/guides/bug_report_templates/benchmark.rb b/guides/bug_report_templates/benchmark.rb
index d0f5a634bc..fb51273e3e 100644
--- a/guides/bug_report_templates/benchmark.rb
+++ b/guides/bug_report_templates/benchmark.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   gem "rails", github: "rails/rails"
   gem "arel", github: "rails/arel"
   gem "benchmark-ips"
diff --git a/guides/bug_report_templates/generic_gem.rb b/guides/bug_report_templates/generic_gem.rb
index c990bda005..60e8322c2a 100644
--- a/guides/bug_report_templates/generic_gem.rb
+++ b/guides/bug_report_templates/generic_gem.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   # Activate the gem you are reporting the issue against.
   gem "activesupport", "5.1.0"
 end
diff --git a/guides/bug_report_templates/generic_master.rb b/guides/bug_report_templates/generic_master.rb
index 1a9b99b624..384c8b1833 100644
--- a/guides/bug_report_templates/generic_master.rb
+++ b/guides/bug_report_templates/generic_master.rb
@@ -9,6 +9,9 @@ end
 
 gemfile(true) do
   source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
   gem "rails", github: "rails/rails"
   gem "arel", github: "rails/arel"
 end
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/engines.md b/guides/source/engines.md
index 343c224a7c..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
diff --git a/guides/source/security.md b/guides/source/security.md
index 9e1dc518d2..a07d583f15 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -152,37 +152,39 @@ 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.
 
-For example to rotate out an old `secret_key_base`, we can define signed and
-encrypted rotations as follows:
+It's possible to rotate the ciphers and digests used for encrypted and signed cookies.
+
+For instance to change the digest used for signed cookies from SHA1 to SHA256,
+you would first assign the new configuration value:
 
 ```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
+Rails.application.config.action_dispatch.signed_cookie_digest = "SHA256"
 ```
 
-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:
+Then you'd set up a rotation with the old configuration to keep it alive.
 
 ```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
 ```
 
+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.
+
+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.