rails 4.2.0 → 4.2.11.3

data/guides/source/active_job_basics.md

@@ -65,33 +65,41 @@ Here's what a job looks like:
 class GuestsCleanupJob < ActiveJob::Base
   queue_as :default
 
-  def perform(*args)
+  def perform(*guests)
     # Do something later
   end
 end
 ```
 
+Note that you can define `perform` with as many arguments as you want.
+
 ### Enqueue the Job
 
 Enqueue a job like so:
 
 ```ruby
-# 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 queuing system is
+# free.
+GuestsCleanupJob.perform_later guest
 ```
 
 ```ruby
 # Enqueue a job to be performed tomorrow at noon.
-MyJob.set(wait_until: Date.tomorrow.noon).perform_later(record)
+GuestsCleanupJob.set(wait_until: Date.tomorrow.noon).perform_later(guest)
 ```
 
 ```ruby
 # Enqueue a job to be performed 1 week from now.
-MyJob.set(wait: 1.week).perform_later(record)
+GuestsCleanupJob.set(wait: 1.week).perform_later(guest)
 ```
 
-That's it!
+```ruby
+# `perform_now` and `perform_later` will call `perform` under the hood so
+# you can pass as many arguments as defined in the latter.
+GuestsCleanupJob.perform_later(guest1, guest2, filter: 'some_filter')
+```
 
+That's it!
 
 Job Execution
 -------------
@@ -266,6 +274,19 @@ UserMailer.welcome(@user).deliver_later
 ```
 
 
+Internationalization
+--------------------
+
+Each job uses the `I18n.locale` set when the job was created. Useful if you send
+emails asynchronously:
+
+```ruby
+I18n.locale = :eo
+
+UserMailer.welcome(@user).deliver_later # Email will be localized to Esparanto.
+```
+
+
 GlobalID
 --------
 

data/guides/source/active_record_basics.md

@@ -171,18 +171,18 @@ name that should be used:
 
 ```ruby
 class Product < ActiveRecord::Base
-  self.table_name = "PRODUCT"
+  self.table_name = "my_products"
 end
 ```
 
 If you do so, you will have to define manually the class name that is hosting
-the fixtures (class_name.yml) using the `set_fixture_class` method in your test
+the fixtures (my_products.yml) using the `set_fixture_class` method in your test
 definition:
 
 ```ruby
-class FunnyJoke < ActiveSupport::TestCase
-  set_fixture_class funny_jokes: Joke
-  fixtures :funny_jokes
+class ProductTest < ActiveSupport::TestCase
+  set_fixture_class my_products: Product
+  fixtures :my_products
   ...
 end
 ```
@@ -258,7 +258,7 @@ david = User.find_by(name: 'David')
 
 ```ruby
 # find all users named David who are Code Artists and sort by created_at in reverse chronological order
-users = User.where(name: 'David', occupation: 'Code Artist').order('created_at DESC')
+users = User.where(name: 'David', occupation: 'Code Artist').order(created_at: :desc)
 ```
 
 You can learn more about querying an Active Record model in the [Active Record

data/guides/source/active_record_querying.md

@@ -332,8 +332,6 @@ User.find_each(start: 2000, batch_size: 5000) do |user|
 end
 ```
 
-Another example would be if you wanted multiple workers handling the same processing queue. You could have each worker handle 10000 records by setting the appropriate `:start` option on each worker.
-
 #### `find_in_batches`
 
 The `find_in_batches` method is similar to `find_each`, since both retrieve batches of records. The difference is that `find_in_batches` yields _batches_ to the block as an array of models, instead of individually. The following example will yield to the supplied block an array of up to 1000 invoices at a time, with the final block containing any remaining invoices:
@@ -876,7 +874,7 @@ For example:
 Item.transaction do
   i = Item.lock.first
   i.name = 'Jones'
-  i.save
+  i.save!
 end
 ```
 

data/guides/source/active_record_validations.md

@@ -944,8 +944,9 @@ own custom validators.
 
 You can also create methods that verify the state of your models and add
 messages to the `errors` collection when they are invalid. You must then
-register these methods by using the `validate` class method, passing in the
-symbols for the validation methods' names.
+register these methods by using the `validate`
+([API](http://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validate))
+class method, passing in the symbols for the validation methods' names.
 
 You can pass more than one symbol for each class method and the respective
 validations will be run in the same order as they were registered.

data/guides/source/active_support_core_extensions.md

@@ -1760,7 +1760,7 @@ NOTE: Defined in `active_support/core_ext/string/inflections.rb`.
 The method `constantize` resolves the constant reference expression in its receiver:
 
 ```ruby
-"Fixnum".constantize # => Fixnum
+"Integer".constantize # => Integer
 
 module M
   X = 1
@@ -2612,8 +2612,7 @@ To do so, the method loops over the pairs and builds nodes that depend on the _v
 ```ruby
 XML_TYPE_NAMES = {
   "Symbol"     => "symbol",
-  "Fixnum"     => "integer",
-  "Bignum"     => "integer",
+  "Integer"    => "integer",
   "BigDecimal" => "decimal",
   "Float"      => "float",
   "TrueClass"  => "boolean",
@@ -3043,53 +3042,6 @@ The method `Range#overlaps?` says whether any two given ranges have non-void int
 
 NOTE: Defined in `active_support/core_ext/range/overlaps.rb`.
 
-Extensions to `Proc`
---------------------
-
-### `bind`
-
-As you surely know Ruby has an `UnboundMethod` class whose instances are methods that belong to the limbo of methods without a self. The method `Module#instance_method` returns an unbound method for example:
-
-```ruby
-Hash.instance_method(:delete) # => #<UnboundMethod: Hash#delete>
-```
-
-An unbound method is not callable as is, you need to bind it first to an object with `bind`:
-
-```ruby
-clear = Hash.instance_method(:clear)
-clear.bind({a: 1}).call # => {}
-```
-
-Active Support defines `Proc#bind` with an analogous purpose:
-
-```ruby
-Proc.new { size }.bind([]).call # => 0
-```
-
-As you see that's callable and bound to the argument, the return value is indeed a `Method`.
-
-NOTE: To do so `Proc#bind` actually creates a method under the hood. If you ever see a method with a weird name like `__bind_1256598120_237302` in a stack trace you know now where it comes from.
-
-Action Pack uses this trick in `rescue_from` for example, which accepts the name of a method and also a proc as callbacks for a given rescued exception. It has to call them in either case, so a bound method is returned by `handler_for_rescue`, thus simplifying the code in the caller:
-
-```ruby
-def handler_for_rescue(exception)
-  _, rescuer = Array(rescue_handlers).reverse.detect do |klass_name, handler|
-    ...
-  end
-
-  case rescuer
-  when Symbol
-    method(rescuer)
-  when Proc
-    rescuer.bind(self)
-  end
-end
-```
-
-NOTE: Defined in `active_support/core_ext/proc.rb`.
-
 Extensions to `Date`
 --------------------
 

data/guides/source/active_support_instrumentation.md

@@ -305,17 +305,6 @@ Action Mailer
 }
 ```
 
-ActiveResource
---------------
-
-### request.active_resource
-
-| Key            | Value                |
-| -------------- | -------------------- |
-| `:method`      | HTTP method          |
-| `:request_uri` | Complete URI         |
-| `:result`      | HTTP response object |
-
 Active Support
 --------------
 

data/guides/source/api_documentation_guidelines.md

@@ -111,7 +111,7 @@ On the other hand, big chunks of structured documentation may have a separate "E
 The results of expressions follow them and are introduced by "# => ", vertically aligned:
 
 ```ruby
-# For checking if a fixnum is even or odd.
+# For checking if an integer is even or odd.
 #
 #   1.even? # => false
 #   1.odd?  # => true

data/guides/source/asset_pipeline.md

@@ -207,7 +207,7 @@ precompiling works.
 
 NOTE: You must have an ExecJS supported runtime in order to use CoffeeScript.
 If you are using Mac OS X or Windows, you have a JavaScript runtime installed in
-your operating system. Check [ExecJS](https://github.com/sstephenson/execjs#readme) documentation to know all supported JavaScript runtimes.
+your operating system. Check [ExecJS](https://github.com/rails/execjs#readme) documentation to know all supported JavaScript runtimes.
 
 You can also disable generation of controller specific asset files by adding the
 following to your `config/application.rb` configuration:
@@ -434,11 +434,11 @@ Sprockets uses manifest files to determine which assets to include and serve.
 These manifest files contain _directives_ - instructions that tell Sprockets
 which files to require in order to build a single CSS or JavaScript file. With
 these directives, Sprockets loads the files specified, processes them if
-necessary, concatenates them into one single file and then compresses them (if
-`Rails.application.config.assets.compress` is true). By serving one file rather
-than many, the load time of pages can be greatly reduced because the browser
-makes fewer requests. Compression also reduces file size, enabling the
-browser to download them faster.
+necessary, concatenates them into one single file and then compresses them
+(based on value of `Rails.application.config.assets.js_compressor`). By serving
+one file rather than many, the load time of pages can be greatly reduced because
+the browser makes fewer requests. Compression also reduces file size, enabling
+the browser to download them faster.
 
 
 For example, a new Rails 4 application includes a default
@@ -727,27 +727,6 @@ include, you can add them to the `precompile` array in `config/initializers/asse
 Rails.application.config.assets.precompile += ['admin.js', 'admin.css', 'swfObject.js']
 ```
 
-Or, you can opt to precompile all assets with something like this:
-
-```ruby
-# config/initializers/assets.rb
-Rails.application.config.assets.precompile << Proc.new do |path|
-  if path =~ /\.(css|js)\z/
-    full_path = Rails.application.assets.resolve(path).to_path
-    app_assets_path = Rails.root.join('app', 'assets').to_path
-    if full_path.starts_with? app_assets_path
-      logger.info "including asset: " + full_path
-      true
-    else
-      logger.info "excluding asset: " + full_path
-      false
-    end
-  else
-    false
-  end
-end
-```
-
 NOTE. Always specify an expected compiled filename that ends with .js or .css,
 even if you want to add Sass or CoffeeScript files to the precompile array.
 
@@ -810,41 +789,6 @@ location ~ ^/assets/ {
 }
 ```
 
-#### GZip Compression
-
-When files are precompiled, Sprockets also creates a
-[gzipped](http://en.wikipedia.org/wiki/Gzip) (.gz) version of your assets. Web
-servers are typically configured to use a moderate compression ratio as a
-compromise, but since precompilation happens once, Sprockets uses the maximum
-compression ratio, thus reducing the size of the data transfer to the minimum.
-On the other hand, web servers can be configured to serve compressed content
-directly from disk, rather than deflating non-compressed files themselves.
-
-NGINX is able to do this automatically enabling `gzip_static`:
-
-```nginx
-location ~ ^/(assets)/  {
-  root /path/to/public;
-  gzip_static on; # to serve pre-gzipped version
-  expires max;
-  add_header Cache-Control public;
-}
-```
-
-This directive is available if the core module that provides this feature was
-compiled with the web server. Ubuntu/Debian packages, even `nginx-light`, have
-the module compiled. Otherwise, you may need to perform a manual compilation:
-
-```bash
-./configure --with-http_gzip_static_module
-```
-
-If you're compiling NGINX with Phusion Passenger you'll need to pass that option
-when prompted.
-
-A robust configuration for Apache is possible but tricky; please Google around.
-(Or help update this Guide if you have a good configuration example for Apache.)
-
 ### Local Precompilation
 
 There are several reasons why you might want to precompile your assets locally.
@@ -1156,7 +1100,7 @@ The following line invokes `uglifier` for JavaScript compression.
 config.assets.js_compressor = :uglifier
 ```
 
-NOTE: You will need an [ExecJS](https://github.com/sstephenson/execjs#readme)
+NOTE: You will need an [ExecJS](https://github.com/rails/execjs#readme)
 supported runtime in order to use `uglifier`. If you are using Mac OS X or
 Windows you have a JavaScript runtime installed in your operating system.
 

data/guides/source/association_basics.md

@@ -169,7 +169,7 @@ class CreateCustomers < ActiveRecord::Migration
     end
 
     create_table :orders do |t|
-      t.belongs_to :customer, index:true
+      t.belongs_to :customer, index: true
       t.datetime :order_date
       t.timestamps null: false
     end
@@ -1417,7 +1417,13 @@ The `collection_singular_ids=` method makes the collection contain only the obje
 
 ##### `collection.clear`
 
-The `collection.clear` method removes every object from the collection. This destroys the associated objects if they are associated with `dependent: :destroy`, deletes them directly from the database if `dependent: :delete_all`, and otherwise sets their foreign keys to `NULL`.
+The `collection.clear` method removes all objects from the collection according to the strategy specified by the `dependent` option. If no option is given, it follows the default strategy. The default strategy for `has_many :through` associations is `delete_all`, and for `has_many` associations is to set the foreign keys to `NULL`.
+
+```ruby
+@customer.orders.clear
+```
+
+WARNING: Objects will be delete if they're associated with `dependent: :destroy`, just like `dependent: :delete_all`.
 
 ##### `collection.empty?`
 
@@ -1456,7 +1462,9 @@ The `collection.where` method finds objects within the collection based on the c
 
 ##### `collection.exists?(...)`
 
-The `collection.exists?` method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as `ActiveRecord::Base.exists?`.
+The `collection.exists?` method checks whether an object meeting the supplied 
+conditions exists in the collection. It uses the same syntax and options as
+[`ActiveRecord::Base.exists?`](http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html#method-i-exists-3F).
 
 ##### `collection.build(attributes = {}, ...)`
 
@@ -1949,7 +1957,9 @@ The `collection.where` method finds objects within the collection based on the c
 
 ##### `collection.exists?(...)`
 
-The `collection.exists?` method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as `ActiveRecord::Base.exists?`.
+The `collection.exists?` method checks whether an object meeting the supplied
+conditions exists in the collection. It uses the same syntax and options as
+[`ActiveRecord::Base.exists?`](http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html#method-i-exists-3F).
 
 ##### `collection.build(attributes = {})`
 
@@ -1977,8 +1987,8 @@ While Rails uses intelligent defaults that will work well in most situations, th
 
 ```ruby
 class Parts < ActiveRecord::Base
-  has_and_belongs_to_many :assemblies, autosave: true,
-                                       readonly: true
+  has_and_belongs_to_many :assemblies, -> { readonly },
+                                       autosave: true
 end
 ```
 
@@ -1990,7 +2000,6 @@ The `has_and_belongs_to_many` association supports these options:
 * `:foreign_key`
 * `:join_table`
 * `:validate`
-* `:readonly`
 
 ##### `:association_foreign_key`
 

data/guides/source/{constant_autoloading_and_reloading.md → autoloading_and_reloading_constants.md}

@@ -1,5 +1,5 @@
-Constant Autoloading and Reloading
-==================================
+Autoloading and Reloading Constants
+===================================
 
 This guide documents how constant autoloading and reloading works.
 
@@ -78,7 +78,8 @@ end
 ```
 
 The *nesting* at any given place is the collection of enclosing nested class and
-module objects outwards. For example, in the previous example, the nesting at
+module objects outwards. The nesting at any given place can be inspected with
+`Module.nesting`. For example, in the previous example, the nesting at
 (1) is
 
 ```ruby
@@ -111,6 +112,16 @@ certain nesting does not necessarily correlate with the namespaces at the spot.
 Even more, they are totally independent, take for instance
 
 ```ruby
+module X
+  module Y
+  end
+end
+
+module A
+  module B
+  end
+end
+
 module X::Y
   module A::B
     # (3)
@@ -138,9 +149,10 @@ executed, and popped after it.
 
 * A singleton class opened with `class << object` gets pushed, and popped later.
 
-* When any of the `*_eval` family of methods is called using a string argument,
+* When `instance_eval` is called using a string argument,
 the singleton class of the receiver is pushed to the nesting of the eval'ed
-code.
+code. When `class_eval` or `module_eval` is called using a string argument,
+the receiver is pushed to the nesting of the eval'ed code.
 
 * The nesting at the top-level of code interpreted by `Kernel#load` is empty
 unless the `load` call receives a true value as second argument, in which case
@@ -151,8 +163,6 @@ the blocks that may be passed to `Class.new` and `Module.new` do not get the
 class or module being defined pushed to their nesting. That's one of the
 differences between defining classes and modules in one way or another.
 
-The nesting at any given place can be inspected with `Module.nesting`.
-
 ### Class and Module Definitions are Constant Assignments
 
 Let's suppose the following snippet creates a class (rather than reopening it):
@@ -186,8 +196,8 @@ Project.name # => "Project"
 ```
 
 Constant assignment has a special rule to make that happen: if the object
-being assigned is an anonymous class or module, Ruby sets its name to be the
-one the constant.
+being assigned is an anonymous class or module, Ruby sets the object's name to
+the name of the constant.
 
 INFO. From then on, what happens to the constant and the instance does not
 matter. For example, the constant could be deleted, the class object could be
@@ -221,7 +231,7 @@ assignment.
 Thus, when one informally says "the `String` class", that really means: the
 class object stored in the constant called "String" in the class object stored
 in the `Object` constant. `String` is otherwise an ordinary Ruby constant and
-everything related to constants applies to it, resolution algorithms, etc.
+everything related to constants such as resolution algorithms applies to it.
 
 Likewise, in the controller
 
@@ -234,7 +244,7 @@ end
 ```
 
 `Post` is not syntax for a class. Rather, `Post` is a regular Ruby constant. If
-all is good, the constant evaluates to an object that responds to `all`.
+all is good, the constant is evaluated to an object that responds to `all`.
 
 That is why we talk about *constant* autoloading, Rails has the ability to
 load constants on the fly.
@@ -256,7 +266,7 @@ module Colors
 end
 ```
 
-First, when the `module` keyword is processed the interpreter creates a new
+First, when the `module` keyword is processed, the interpreter creates a new
 entry in the constant table of the class object stored in the `Object` constant.
 Said entry associates the name "Colors" to a newly created module object.
 Furthermore, the interpreter sets the name of the new module object to be the
@@ -270,7 +280,7 @@ In particular, `Colors::RED` is totally unrelated to any other `RED` constant
 that may live in any other class or module object. If there were any, they
 would have separate entries in their respective constant tables.
 
-Put special attention in the previous paragraphs to the distinction between
+Pay special attention in the previous paragraphs to the distinction between
 class and module objects, constant names, and value objects associated to them
 in constant tables.
 
@@ -289,12 +299,14 @@ order. The ancestors of those elements are ignored.
 
 2. If not found, then the algorithm walks up the ancestor chain of the cref.
 
-3. If not found, `const_missing` is invoked on the cref. The default
+3. If not found and the cref is a module, the constant is looked up in `Object`.
+
+4. If not found, `const_missing` is invoked on the cref. The default
 implementation of `const_missing` raises `NameError`, but it can be overridden.
 
 Rails autoloading **does not emulate this algorithm**, but its starting point is
 the name of the constant to be autoloaded, and the cref. See more in [Relative
-References](#relative-references).
+References](#autoloading-algorithms-relative-references).
 
 #### Resolution Algorithm for Qualified Constants
 
@@ -312,7 +324,7 @@ relative: `::Billing::Invoice`. That would force `Billing` to be looked up
 only as a top-level constant.
 
 `Invoice` on the other hand is qualified by `Billing` and we are going to see
-its resolution next. Let's call *parent* to that qualifying class or module
+its resolution next. Let's define *parent* to be that qualifying class or module
 object, that is, `Billing` in the example above. The algorithm for qualified
 constants goes like this:
 
@@ -328,7 +340,7 @@ checked.
 
 Rails autoloading **does not emulate this algorithm**, but its starting point is
 the name of the constant to be autoloaded, and the parent. See more in
-[Qualified References](#qualified-references).
+[Qualified References](#autoloading-algorithms-qualified-references).
 
 
 Vocabulary
@@ -439,18 +451,19 @@ default it contains:
   `app/controllers`. They do not need to be the default ones, any custom
   directories like `app/workers` belong automatically to `autoload_paths`.
 
-* Any existing second level directories called `app/*/concerns` in the
+* Second level directories `app/{controllers,models}/concerns` in the
   application and engines.
 
 * The directory `test/mailers/previews`.
 
 Also, this collection is configurable via `config.autoload_paths`. For example,
 `lib` was in the list years ago, but no longer is. An application can opt-in
-throwing this to `config/application.rb`:
+by adding this to `config/application.rb`:
 
 ```ruby
-config.autoload_paths += "#{Rails.root}/lib"
+config.autoload_paths << "#{Rails.root}/lib"
 ```
+`config.autoload_paths` is accessible from environment-specific configuration files, but any changes made to it outside `config/application.rb` don't have an effect.
 
 The value of `autoload_paths` can be inspected. In a just generated application
 it is (edited):
@@ -683,12 +696,12 @@ creates an empty module and assigns it to the `Admin` constant on the fly.
 ### Generic Procedure
 
 Relative references are reported to be missing in the cref where they were hit,
-and qualified references are reported to be missing in their parent. (See
+and qualified references are reported to be missing in their parent (see
 [Resolution Algorithm for Relative
 Constants](#resolution-algorithm-for-relative-constants) at the beginning of
 this guide for the definition of *cref*, and [Resolution Algorithm for Qualified
 Constants](#resolution-algorithm-for-qualified-constants) for the definition of
-*parent*.)
+*parent*).
 
 The procedure to autoload constant `C` in an arbitrary situation is as follows:
 
@@ -866,8 +879,8 @@ end
 ```
 
 To resolve `User` Ruby checks `Admin` in the former case, but it does not in
-the latter because it does not belong to the nesting. (See [Nesting](#nesting)
-and [Resolution Algorithms](#resolution-algorithms).)
+the latter because it does not belong to the nesting (see [Nesting](#nesting)
+and [Resolution Algorithms](#resolution-algorithms)).
 
 Unfortunately Rails autoloading does not know the nesting in the spot where the
 constant was missing and so it is not able to act as Ruby would. In particular,
@@ -889,7 +902,7 @@ end
 
 ### Autoloading and STI
 
-Single Table Inheritance (STI) is a feature of Active Record that easies
+Single Table Inheritance (STI) is a feature of Active Record that enables
 storing a hierarchy of models in one single table. The API of such models is
 aware of the hierarchy and encapsulates some common needs. For example, given
 these classes:
@@ -1171,7 +1184,8 @@ class Hotel
 end
 ```
 
-the expression `Hotel::Image` is ambiguous, depends on the execution path.
+the expression `Hotel::Image` is ambiguous because it depends on the execution
+path.
 
 As [we saw before](#resolution-algorithm-for-qualified-constants), Ruby looks
 up the constant in `Hotel` and its ancestors. If `app/models/image.rb` has
@@ -1280,8 +1294,8 @@ c.user # surprisingly fine, User
 c.user # NameError: uninitialized constant C::User
 ```
 
-because it detects a parent namespace already has the constant (see [Qualified
-References](#qualified-references).)
+because it detects that a parent namespace already has the constant (see [Qualified
+References](#autoloading-algorithms-qualified-references)).
 
 As with pure Ruby, within the body of a direct descendant of `BasicObject` use
 always absolute constant paths: