13 files changed, 93 insertions, 51 deletions
diff --git a/guides/rails_guides/markdown.rb b/guides/rails_guides/markdown.rb
index 1ea18ba9f5..b422a80759 100644
--- a/guides/rails_guides/markdown.rb
+++ b/guides/rails_guides/markdown.rb
@@ -47,7 +47,7 @@ module RailsGuides
       end
 
       def dom_id_text(text)
-        text.downcase.gsub(/\?/, '-questionmark').gsub(/!/, '-bang').gsub(/\s+/, '-')
+        text.downcase.gsub(/\?/, '-questionmark').gsub(/!/, '-bang').gsub(/[^a-z0-9]+/, ' ').strip.gsub(/\s+/, '-')
       end
 
       def engine
diff --git a/guides/source/2_2_release_notes.md b/guides/source/2_2_release_notes.md
index 522f628a7e..b11aaa15a8 100644
--- a/guides/source/2_2_release_notes.md
+++ b/guides/source/2_2_release_notes.md
@@ -1,7 +1,7 @@
 Ruby on Rails 2.2 Release Notes
 ===============================
 
-Rails 2.2 delivers a number of new and improved features. This list covers the major upgrades, but doesn't include every little bug fix and change. If you want to see everything, check out the [list of commits](http://github.com/rails/rails/commits/master) in the main Rails repository on GitHub.
+Rails 2.2 delivers a number of new and improved features. This list covers the major upgrades, but doesn't include every little bug fix and change. If you want to see everything, check out the [list of commits](http://github.com/rails/rails/commits/2-2-stable) in the main Rails repository on GitHub.
 
 Along with Rails, 2.2 marks the launch of the [Ruby on Rails Guides](http://guides.rubyonrails.org/), the first results of the ongoing [Rails Guides hackfest](http://hackfest.rubyonrails.org/guide). This site will deliver high-quality documentation of the major features of Rails.
 
diff --git a/guides/source/2_3_release_notes.md b/guides/source/2_3_release_notes.md
index 52eeb4c2bc..20566c9155 100644
--- a/guides/source/2_3_release_notes.md
+++ b/guides/source/2_3_release_notes.md
@@ -1,7 +1,7 @@
 Ruby on Rails 2.3 Release Notes
 ===============================
 
-Rails 2.3 delivers a variety of new and improved features, including pervasive Rack integration, refreshed support for Rails Engines, nested transactions for Active Record, dynamic and default scopes, unified rendering, more efficient routing, application templates, and quiet backtraces. This list covers the major upgrades, but doesn't include every little bug fix and change. If you want to see everything, check out the [list of commits](http://github.com/rails/rails/commits/master) in the main Rails repository on GitHub or review the `CHANGELOG` files for the individual Rails components.
+Rails 2.3 delivers a variety of new and improved features, including pervasive Rack integration, refreshed support for Rails Engines, nested transactions for Active Record, dynamic and default scopes, unified rendering, more efficient routing, application templates, and quiet backtraces. This list covers the major upgrades, but doesn't include every little bug fix and change. If you want to see everything, check out the [list of commits](http://github.com/rails/rails/commits/2-3-stable) in the main Rails repository on GitHub or review the `CHANGELOG` files for the individual Rails components.
 
 --------------------------------------------------------------------------------
 
diff --git a/guides/source/3_0_release_notes.md b/guides/source/3_0_release_notes.md
index aec3a383d6..8122d6c235 100644
--- a/guides/source/3_0_release_notes.md
+++ b/guides/source/3_0_release_notes.md
@@ -15,7 +15,7 @@ Even if you don't give a hoot about any of our internal cleanups, Rails 3.0 is g
 
 On top of all that, we've tried our best to deprecate the old APIs with nice warnings. That means that you can move your existing application to Rails 3 without immediately rewriting all your old code to the latest best practices.
 
-These release notes cover the major upgrades, but don't include every little bug fix and change. Rails 3.0 consists of almost 4,000 commits by more than 250 authors! If you want to see everything, check out the [list of commits](http://github.com/rails/rails/commits/master) in the main Rails repository on GitHub.
+These release notes cover the major upgrades, but don't include every little bug fix and change. Rails 3.0 consists of almost 4,000 commits by more than 250 authors! If you want to see everything, check out the [list of commits](http://github.com/rails/rails/commits/3-0-stable) in the main Rails repository on GitHub.
 
 --------------------------------------------------------------------------------
 
diff --git a/guides/source/3_1_release_notes.md b/guides/source/3_1_release_notes.md
index 7626296e7d..b7ed285b96 100644
--- a/guides/source/3_1_release_notes.md
+++ b/guides/source/3_1_release_notes.md
@@ -8,7 +8,10 @@ Highlights in Rails 3.1:
 * Assets Pipeline
 * jQuery as the default JavaScript library
 
-This release notes cover the major changes, but don't include every little bug fix and change. If you want to see everything, check out the [list of commits](https://github.com/rails/rails/commits/master) in the main Rails repository on GitHub.
+These release notes cover only the major changes. To learn about various bug
+fixes and changes, please refer to the change logs or check out the [list of
+commits](https://github.com/rails/rails/commits/3-1-stable) in the main Rails
+repository on GitHub.
 
 --------------------------------------------------------------------------------
 
diff --git a/guides/source/3_2_release_notes.md b/guides/source/3_2_release_notes.md
index 2416e1a228..c5db0262e9 100644
--- a/guides/source/3_2_release_notes.md
+++ b/guides/source/3_2_release_notes.md
@@ -8,7 +8,10 @@ Highlights in Rails 3.2:
 * Automatic Query Explains
 * Tagged Logging
 
-These release notes cover the major changes, but do not include each bug-fix and changes. If you want to see everything, check out the [list of commits](https://github.com/rails/rails/commits/3-2-stable) in the main Rails repository on GitHub.
+These release notes cover only the major changes. To learn about various bug
+fixes and changes, please refer to the change logs or check out the [list of
+commits](https://github.com/rails/rails/commits/3-2-stable) in the main Rails
+repository on GitHub.
 
 --------------------------------------------------------------------------------
 
diff --git a/guides/source/4_0_release_notes.md b/guides/source/4_0_release_notes.md
index 19c690233c..1aaf5ebc94 100644
--- a/guides/source/4_0_release_notes.md
+++ b/guides/source/4_0_release_notes.md
@@ -8,7 +8,10 @@ Highlights in Rails 4.0:
 * Turbolinks
 * Russian Doll Caching
 
-These release notes cover only the major changes. To know about various bug fixes and changes, please refer to the change logs or check out the [list of commits](https://github.com/rails/rails/commits/master) in the main Rails repository on GitHub.
+These release notes cover only the major changes. To learn about various bug
+fixes and changes, please refer to the change logs or check out the [list of
+commits](https://github.com/rails/rails/commits/4-0-stable) in the main Rails
+repository on GitHub.
 
 --------------------------------------------------------------------------------
 
diff --git a/guides/source/4_1_release_notes.md b/guides/source/4_1_release_notes.md
index 5f4bdaaa8f..52a5acb75e 100644
--- a/guides/source/4_1_release_notes.md
+++ b/guides/source/4_1_release_notes.md
@@ -8,10 +8,10 @@ Highlights in Rails 4.1:
 * Action Pack variants
 * Action Mailer previews
 
-These release notes cover only the major changes. To know about various bug
-fixes and changes, please refer to the change logs or check out the
-[list of commits](https://github.com/rails/rails/commits/master) in the main
-Rails repository on GitHub.
+These release notes cover only the major changes. To learn about various bug
+fixes and changes, please refer to the change logs or check out the [list of
+commits](https://github.com/rails/rails/commits/4-1-stable) in the main Rails
+repository on GitHub.
 
 --------------------------------------------------------------------------------
 
diff --git a/guides/source/4_2_release_notes.md b/guides/source/4_2_release_notes.md
index d362c8cd58..913bb4fb5f 100644
--- a/guides/source/4_2_release_notes.md
+++ b/guides/source/4_2_release_notes.md
@@ -8,10 +8,10 @@ Highlights in Rails 4.2:
 * Web Console
 * Foreign key support
 
-These release notes cover only the major changes. To know about various bug
-fixes and changes, please refer to the change logs or check out the
-[list of commits](https://github.com/rails/rails/commits/master) in the main
-Rails repository on GitHub.
+These release notes cover only the major changes. To learn about various bug
+fixes and changes, please refer to the change logs or check out the [list of
+commits](https://github.com/rails/rails/commits/master) in the main Rails
+repository on GitHub.
 
 --------------------------------------------------------------------------------
 
@@ -26,7 +26,7 @@ coverage before going in. You should also first upgrade to Rails 4.1 in case you
 haven't and make sure your application still runs as expected before attempting
 to upgrade to Rails 4.2. A list of things to watch out for when upgrading is
 available in the
-[Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-4.1-to-rails-4.2)
+[Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-4-1-to-rails-4-2)
 guide.
 
 
@@ -311,6 +311,9 @@ Please refer to the [Changelog][action-mailer] for detailed changes.
 *   Deprecated `*_path` helpers in mailers. Always use `*_url` helpers instead.
     ([Pull Request](https://github.com/rails/rails/pull/15840))
 
+*   Deprecated `deliver` / `deliver!` in favour of `deliver_now` / `deliver_now!`.
+    ([Pull Request](https://github.com/rails/rails/pull/16582))
+
 ### Notable changes
 
 *   Introduced `deliver_later` which enqueues a job on the application's queue
diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md
index 9ad9319255..6b6ce145e4 100644
--- a/guides/source/action_mailer_basics.md
+++ b/guides/source/action_mailer_basics.md
@@ -159,7 +159,10 @@ $ bin/rake 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.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:
 
 ```ruby
 class UsersController < ApplicationController
@@ -171,7 +174,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
+        UserMailer.welcome_email(@user).deliver_later
 
         format.html { redirect_to(@user, notice: 'User was successfully created.') }
         format.json { render json: @user, status: :created, location: @user }
@@ -184,8 +187,29 @@ class UsersController < ApplicationController
 end
 ```
 
-The method `welcome_email` returns a `Mail::Message` object which can then just
-be told `deliver` to send itself out.
+NOTE: By default Active Job is configured to execute the job `:inline`. So you can
+use `deliver_later` now to send the emails and when you decide to start sending the
+email from a background job you'll just have to setup Active Job to use a queueing
+backend (Sidekiq, Resque, etc).
+
+If you want to send the emails right away (from a cronjob for example) just
+call `deliver_now`:
+
+```ruby
+class SendWeeklySummary
+  def run
+    User.find_each do |user|
+      UserMailer.weekly_summary(user).deliver_now
+    end
+  end
+end
+```
+
+The method `welcome_email` returns a `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
+you want to inspect, alter or do anything else with the `Mail::Message` object you can
+access it with the `message` method on the `ActionMailer::MessageDelivery` object.
 
 ### Auto encoding header values
 
diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md
index ae5d21d546..a8e1f22b4d 100644
--- a/guides/source/active_job_basics.md
+++ b/guides/source/active_job_basics.md
@@ -13,12 +13,13 @@ After reading this guide, you will know:
 
 --------------------------------------------------------------------------------
 
+
 Introduction
 ------------
 
 Active Job is a framework for declaring jobs and making them run on a variety
 of queueing backends. These jobs can be everything from regularly scheduled
-clean-ups, billing charges, or mailings. Anything that can be chopped up
+clean-ups, to billing charges, to mailings. Anything that can be chopped up
 into small units of work and run in parallel, really.
 
 
@@ -35,12 +36,12 @@ then. And you'll be able to switch between them without having to rewrite your j
 Creating a Job
 --------------
 
-This section will provide a step-by-step guide to creating a job and enqueue it.
+This section will provide a step-by-step guide to creating a job and enqueuing it.
 
 ### Create the Job
 
 Active Job provides a Rails generator to create jobs. The following will create a
-job in app/jobs:
+job in `app/jobs`:
 
 ```bash
 $ bin/rails generate job guests_cleanup
@@ -58,9 +59,9 @@ As you can see, you can generate jobs just like you use other generators with
 Rails.
 
 If you don't want to use a generator, you could create your own file inside of
-app/jobs, just make sure that it inherits from `ActiveJob::Base`.
+`app/jobs`, just make sure that it inherits from `ActiveJob::Base`.
 
-Here's how a job looks like:
+Here's what a job looks like:
 
 ```ruby
 class GuestsCleanupJob < ActiveJob::Base
@@ -94,7 +95,7 @@ That's it!
 Job Execution
 -------------
 
-If not adapter is set, the job is immediately executed.
+If no adapter is set, the job is immediately executed.
 
 ### Backends
 
@@ -127,7 +128,7 @@ Active Job has adapters for the following queueing backends:
 
 ### Change Backends
 
-You can easy change your adapter:
+You can easily change your adapter:
 
 ```ruby
 # be sure to have the adapter gem in your Gemfile and follow the adapter specific
@@ -135,11 +136,12 @@ You can easy change your adapter:
 YourApp::Application.config.active_job.queue_adapter = :sidekiq
 ```
 
+
 Queues
 ------
 
-Most of the adapters supports multiple queues. With Active Job you can schedule the job
-to run on a specific queue:
+Most of the adapters support multiple queues. With Active Job you can schedule
+the job to run on a specific queue:
 
 ```ruby
 class GuestsCleanupJob < ActiveJob::Base
@@ -155,17 +157,17 @@ you need to specify the queues to listen to.
 Callbacks
 ---------
 
-Active Job provides hooks during the lifecycle of a job. Callbacks allows you to trigger
-logic during the lifecycle of a job.
+Active Job provides hooks during the lifecycle of a job. Callbacks allow you to
+trigger logic during the lifecycle of a job.
 
 ### Available callbacks
 
-* before_enqueue
-* around_enqueue
-* after_enqueue
-* before_perform
-* around_perform
-* after_perform
+* `before_enqueue`
+* `around_enqueue`
+* `after_enqueue`
+* `before_perform`
+* `around_perform`
+* `after_perform`
 
 ### Usage
 
@@ -189,25 +191,28 @@ class GuestsCleanupJob < ActiveJob::Base
 end
 ```
 
+
 ActionMailer
 ------------
+
 One of the most common jobs in a modern web application is sending emails outside
 of the request-response cycle, so the user doesn't have to wait on it. Active Job
-is integrated with Action Mailer so you can easily send emails async:
+is integrated with Action Mailer so you can easily send emails asynchronously:
 
 ```ruby
-# Instead of the classic
-UserMailer.welcome(@user).deliver
+# If you want to send the email now use #deliver_now
+UserMailer.welcome(@user).deliver_now
 
-# use #deliver later to send the email async
+# If you want to send the email through ActiveJob use #deliver_later
 UserMailer.welcome(@user).deliver_later
 ```
 
+
 GlobalID
 --------
-Active Job supports GlobalID for parameters. This makes it possible
-to pass live Active Record objects to your job instead of class/id pairs, which
-you then have to manually deserialize. Before, jobs would look like this:
+Active Job supports GlobalID for parameters. This makes it possible to pass live
+Active Record objects to your job instead of class/id pairs, which you then have
+to manually deserialize. Before, jobs would look like this:
 
 ```ruby
 class TrashableCleanupJob
@@ -228,12 +233,13 @@ class TrashableCleanupJob
 end
 ```
 
-This works with any class that mixes in ActiveModel::GlobalIdentification, which
+This works with any class that mixes in `ActiveModel::GlobalIdentification`, which
 by default has been mixed into Active Model classes.
 
 
 Exceptions
 ----------
+
 Active Job provides a way to catch exceptions raised during the execution of the
 job:
 
diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index f9b46286c1..cb243c95f5 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -276,7 +276,7 @@ This may appear straightforward:
 ```ruby
 # This is very inefficient when the users table has thousands of rows.
 User.all.each do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
@@ -292,7 +292,7 @@ The `find_each` method retrieves a batch of records and then yields _each_ recor
 
 ```ruby
 User.find_each do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
@@ -300,7 +300,7 @@ To add conditions to a `find_each` operation you can chain other Active Record m
 
 ```ruby
 User.where(weekly_subscriber: true).find_each do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
@@ -316,7 +316,7 @@ The `:batch_size` option allows you to specify the number of records to be retri
 
 ```ruby
 User.find_each(batch_size: 5000) do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
@@ -328,7 +328,7 @@ For example, to send newsletters only to users with the primary key starting fro
 
 ```ruby
 User.find_each(start: 2000, batch_size: 5000) do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
diff --git a/guides/source/testing.md b/guides/source/testing.md
index 2ecd560a87..d91f13699a 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -949,7 +949,7 @@ class UserMailerTest < ActionMailer::TestCase
   test "invite" do
     # Send the email, then test that it got queued
     email = UserMailer.create_invite('me@example.com',
-                                     'friend@example.com', Time.now).deliver
+                                     'friend@example.com', Time.now).deliver_now
     assert_not ActionMailer::Base.deliveries.empty?
 
     # Test the body of the sent email contains what we expect it to