rails 4.2.0.beta1 → 4.2.0.beta2

data/guides/source/action_controller_overview.md

@@ -1183,9 +1183,9 @@ First define your app own routes to display the errors page.
 * `config/routes.rb`
 
   ```ruby
-  get '/404', to: 'errors#not_found'
-  get '/422', to: 'errors#unprocessable_entity'
-  get '/500', to: 'errors#server_error'
+  match '/404', via: :all, to: 'errors#not_found'
+  match '/422', via: :all, to: 'errors#unprocessable_entity'
+  match '/500', via: :all, to: 'errors#server_error'
   ```
 
 Create the controller and views.

data/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: Active Job's default behavior is to execute jobs ':inline'. So, you can use
+`deliver_later` now to send emails, and when you later decide to start sending
+them from a background job, you'll only need to set up Active Job to use a queueing
+backend (Sidekiq, Resque, etc).
+
+If you want to send 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
 

data/guides/source/action_view_overview.md

@@ -44,18 +44,18 @@ $ bin/rails generate scaffold article
 
 There is a naming convention for views in Rails. Typically, the views share their name with the associated controller action, as you can see above.
 For example, the index controller action of the `articles_controller.rb` will use the `index.html.erb` view file in the `app/views/articles` directory.
-The complete HTML returned to the client is composed of a combination of this ERB file, a layout template that wraps it, and all the partials that the view may reference. Later on this guide you can find a more detailed documentation of each one of these three components.
+The complete HTML returned to the client is composed of a combination of this ERB file, a layout template that wraps it, and all the partials that the view may reference. Within this guide you will find more detailed documentation about each of these three components.
 
 
 Templates, Partials and Layouts
 -------------------------------
 
-As mentioned before, the final HTML output is a composition of three Rails elements: `Templates`, `Partials` and `Layouts`.
-Below is a brief overview of each one of them.
+As mentioned, the final HTML output is a composition of three Rails elements: `Templates`, `Partials` and `Layouts`.
+Below is a brief overview of each of them.
 
 ### Templates
 
-Action View templates can be written in several ways. If the template file has a `.erb` extension then it uses a mixture of ERB (included in Ruby) and HTML. If the template file has a `.builder` extension then a fresh instance of `Builder::XmlMarkup` library is used.
+Action View templates can be written in several ways. If the template file has a `.erb` extension then it uses a mixture of ERB (Embedded Ruby) and HTML. If the template file has a `.builder` extension then the `Builder::XmlMarkup` library is used.
 
 Rails supports multiple template systems and uses a file extension to distinguish amongst them. For example, an HTML file using the ERB template system will have `.html.erb` as a file extension.
 
@@ -72,7 +72,7 @@ Consider the following loop for names:
 <% end %>
 ```
 
-The loop is set up in regular embedding tags (`<% %>`) and the name is written using the output embedding tags (`<%= %>`). Note that this is not just a usage suggestion, for regular output functions like `print` or `puts` won't work with ERB templates. So this would be wrong:
+The loop is set up using regular embedding tags (`<% %>`) and the name is inserted using the output embedding tags (`<%= %>`). Note that this is not just a usage suggestion: regular output functions such as `print` and `puts` won't be rendered to the view with ERB templates. So this would be wrong:
 
 ```html+erb
 <%# WRONG %>
@@ -231,7 +231,7 @@ The `object` and `as` options can also be used together:
 
 #### Rendering Collections
 
-It is very common that a template needs to iterate over a collection and render a sub-template for each of the elements. This pattern has been implemented as a single method that accepts an array and renders a partial for each one of the elements in the array.
+It is very common that a template will need to iterate over a collection and render a sub-template for each of the elements. This pattern has been implemented as a single method that accepts an array and renders a partial for each one of the elements in the array.
 
 So this example for rendering all the products:
 
@@ -247,7 +247,7 @@ can be rewritten in a single line:
 <%= render partial: "product", collection: @products %>
 ```
 
-When a partial is called like this (eg. with a collection), the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is `_product`, and within it you can refer to `product` to get the instance that is being rendered.
+When a partial is called with a collection, the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is `_product`, and within it you can refer to `product` to get the collection member that is being rendered.
 
 You can use a shorthand syntax for rendering collections. Assuming `@products` is a collection of `Product` instances, you can simply write the following to produce the same result:
 
@@ -255,7 +255,7 @@ You can use a shorthand syntax for rendering collections. Assuming `@products` i
 <%= render @products %>
 ```
 
-Rails determines the name of the partial to use by looking at the model name in the collection, `Product` in this case. In fact, you can even create a heterogeneous collection and render it this way, and Rails will choose the proper partial for each member of the collection.
+Rails determines the name of the partial to use by looking at the model name in the collection, `Product` in this case. In fact, you can even render a collection made up of instances of different models using this shorthand, and Rails will choose the proper partial for each member of the collection.
 
 #### Spacer Templates
 
@@ -269,14 +269,14 @@ Rails will render the `_product_ruler` partial (with no data passed to it) betwe
 
 ### Layouts
 
-Layouts can be used to render a common view template around the results of Rails controller actions. Typically, every Rails application has a couple of overall layouts that most pages are rendered within. For example, a site might have a layout for a logged in user, and a layout for the marketing or sales side of the site. The logged in user layout might include top-level navigation that should be present across many controller actions. The sales layout for a SaaS app might include top-level navigation for things like "Pricing" and "Contact Us." You would expect each layout to have a different look and feel. You can read more details about Layouts in the [Layouts and Rendering in Rails](layouts_and_rendering.html) guide.
+Layouts can be used to render a common view template around the results of Rails controller actions. Typically, a Rails application will have a couple of layouts that pages will be rendered within. For example, a site might have one layout for a logged in user and another for the marketing or sales side of the site. The logged in user layout might include top-level navigation that should be present across many controller actions. The sales layout for a SaaS app might include top-level navigation for things like "Pricing" and "Contact Us" pages. You would expect each layout to have a different look and feel. You can read about layouts in more detail in the [Layouts and Rendering in Rails](layouts_and_rendering.html) guide.
 
 Partial Layouts
 ---------------
 
-Partials can have their own layouts applied to them. These layouts are different than the ones that are specified globally for the entire action, but they work in a similar fashion.
+Partials can have their own layouts applied to them. These layouts are different from those applied to a controller action, but they work in a similar fashion.
 
-Let's say we're displaying an article on a page, that should be wrapped in a `div` for display purposes. First, we'll create a new `Article`:
+Let's say we're displaying an article on a page which should be wrapped in a `div` for display purposes. Firstly, we'll create a new `Article`:
 
 ```ruby
 Article.create(body: 'Partial Layouts are cool!')

data/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,15 +59,15 @@ 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
   queue_as :default
 
-  def perform
+  def perform(*args)
     # Do something later
   end
 end
@@ -77,15 +78,15 @@ end
 Enqueue a job like so:
 
 ```ruby
-MyJob.enqueue record  # Enqueue a job to be performed as soon the queueing system is free.
+MyJob.perform_later record  # Enqueue a job to be performed as soon the queueing system is free.
 ```
 
 ```ruby
-MyJob.enqueue_at Date.tomorrow.noon, record  # Enqueue a job to be performed tomorrow at noon.
+MyJob.set(wait_until: Date.tomorrow.noon).perform_later(record)  # Enqueue a job to be performed tomorrow at noon.
 ```
 
 ```ruby
-MyJob.enqueue_in 1.week, record # Enqueue a job to be performed 1 week from now.
+MyJob.set(wait: 1.week).perform_later(record) # Enqueue a job to be performed 1 week from now.
 ```
 
 That's it!
@@ -94,52 +95,30 @@ 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
 
-Active Job has adapters for the following queueing backends:
-
-* [Backburner](https://github.com/nesquena/backburner)
-* [Delayed Job](https://github.com/collectiveidea/delayed_job)
-* [Qu](https://github.com/bkeepers/qu)
-* [Que](https://github.com/chanks/que)
-* [QueueClassic](https://github.com/ryandotsmith/queue_classic)
-* [Resque 1.x](https://github.com/resque/resque)
-* [Sidekiq](https://github.com/mperham/sidekiq)
-* [Sneakers](https://github.com/jondot/sneakers)
-* [Sucker Punch](https://github.com/brandonhilkert/sucker_punch)
-
-#### Backends Features
-
-|                       | Async | Queues  | Delayed | Priorities  | Timeout | Retries |
-|-----------------------|-------|---------|---------|-------------|---------|---------|
-| **Backburner**        | Yes   | Yes     | Yes     | Yes         | Job     | Global  |
-| **Delayed Job**       | Yes   | Yes     | Yes     | Job         | Global  | Global  |
-| **Que**               | Yes   | Yes     | Yes     | Job         | No      | Job     |
-| **Queue Classic**     | Yes   | Yes     | Gem     | No          | No      | No      |
-| **Resque**            | Yes   | Yes     | Gem     | Queue       | Global  | ?       |
-| **Sidekiq**           | Yes   | Yes     | Yes     | Queue       | No      | Job     |
-| **Sneakers**          | Yes   | Yes     | No      | Queue       | Queue   | No      |
-| **Sucker Punch**      | Yes   | Yes     | Yes     | No          | No      | No      |
-| **Active Job**        | Yes   | Yes     | WIP     | No          | No      | No      |
-| **Active Job Inline** | No    | Yes     | N/A     | N/A         | N/A     | N/A     |
-
-### Change Backends
-
-You can easy change your adapter:
+Active Job has  built-in adapters for multiple queueing backends (Sidekiq,
+Resque, Delayed Job and others). To get an up-to-date list of the adapters
+see the API Documentation for [ActiveJob::QueueAdapters](http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html).
+
+### Changing the Backend
+
+You can easily change your queueing backend:
 
 ```ruby
 # be sure to have the adapter gem in your Gemfile and follow the adapter specific
 # installation and deployment instructions
-YourApp::Application.config.active_job.queue_adapter = :sidekiq
+Rails.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
@@ -148,24 +127,77 @@ class GuestsCleanupJob < ActiveJob::Base
 end
 ```
 
-NOTE: Make sure your queueing backend "listens" on your queue name. For some backends
-you need to specify the queues to listen to.
+You can prefix the queue name for all your jobs using
+`config.active_job.queue_name_prefix` in `application.rb`:
+
+```ruby
+# config/application.rb
+module YourApp
+  class Application < Rails::Application
+    config.active_job.queue_name_prefix = Rails.env
+  end
+end
+
+# app/jobs/guests_cleanup.rb
+class GuestsCleanupJob < ActiveJob::Base
+  queue_as :low_priority
+  #....
+end
+
+# Now your job will run on queue production_low_priority on your
+# production environment and on beta_low_priority on your beta
+# environment
+```
+
+If you want more control on what queue a job will be run you can pass a :queue
+option to #set:
+
+```ruby
+MyJob.set(queue: :another_queue).perform_later(record)
+```
+
+To control the queue from the job level you can pass a block to queue_as. The
+block will be executed in the job context (so you can access self.arguments)
+and you must return the queue name:
+
+```ruby
+class ProcessVideoJob < ActiveJob::Base
+  queue_as do
+    video = self.arguments.first
+    if video.owner.premium?
+      :premium_videojobs
+    else
+      :videojobs
+    end
+  end
+
+  def perform(video)
+    # do process video
+  end
+end
+
+ProcessVideoJob.perform_later(Video.last)
+```
+
+
+NOTE: Make sure your queueing backend "listens" on your queue name. For some
+backends 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
 
@@ -174,7 +206,7 @@ class GuestsCleanupJob < ActiveJob::Base
   queue_as :default
 
   before_enqueue do |job|
-    # do somthing with the job instance
+    # do something with the job instance
   end
 
   around_perform do |job, block|
@@ -189,25 +221,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 Active Job 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 +263,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:
 
@@ -242,7 +278,7 @@ job:
 class GuestsCleanupJob < ActiveJob::Base
   queue_as :default
 
-  rescue_from(ActiveRecord:NotFound) do |exception|
+  rescue_from(ActiveRecord::RecordNotFound) do |exception|
    # do something with the exception
   end
 

data/guides/source/active_record_postgresql.md

@@ -132,7 +132,8 @@ event = Event.first
 event.payload # => {"kind"=>"user_renamed", "change"=>["jack", "john"]}
 
 ## Query based on JSON document
-Event.where("payload->'kind' = ?", "user_renamed")
+# The -> operator returns the original JSON type (which might be an object), whereas ->> returns text
+Event.where("payload->>'kind' = ?", "user_renamed")
 ```
 
 ### Range Types

data/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
 ```
 
@@ -340,16 +340,14 @@ The `find_in_batches` method is similar to `find_each`, since both retrieve batc
 
 ```ruby
 # Give add_invoices an array of 1000 invoices at a time
-Invoice.find_in_batches(include: :invoice_lines) do |invoices|
+Invoice.find_in_batches do |invoices|
   export.add_invoices(invoices)
 end
 ```
 
-NOTE: The `:include` option allows you to name associations that should be loaded alongside with the models.
-
 ##### Options for `find_in_batches`
 
-The `find_in_batches` method accepts the same `:batch_size` and `:start` options as `find_each`, as well as most of the options allowed by the regular `find` method, except for `:order` and `:limit`, which are reserved for internal use by `find_in_batches`.
+The `find_in_batches` method accepts the same `:batch_size` and `:start` options as `find_each`.
 
 Conditions
 ----------