Merge branch 'master' of github.com:lifo/docrails

17 files changed, 260 insertions, 129 deletions

diff --git a/actionpack/lib/abstract_controller/layouts.rb b/actionpack/lib/abstract_controller/layouts.rb
index 92e93cbee7..a82e3dc90a 100644
--- a/actionpack/lib/abstract_controller/layouts.rb
+++ b/actionpack/lib/abstract_controller/layouts.rb
@@ -136,8 +136,8 @@ module AbstractController
   #     layout "weblog_standard"
   #   end
   #
-  # If no directory is specified for the template name, the template will by default be looked for in <tt>app/views/layouts/</tt>.
-  # Otherwise, it will be looked up relative to the template root.
+  # The template will be looked always in <tt>app/views/layouts/</tt> folder. But you can point
+  # <tt>layouts</tt> folder direct also. <tt>layout "layouts/demo"</tt> is the same as <tt>layout "demo"</tt>.
   #
   # Setting the layout to nil forces it to be looked up in the filesystem and fallbacks to the parent behavior if none exists.
   # Setting it to nil is useful to re-enable template lookup overriding a previous configuration set in the parent:
@@ -238,8 +238,7 @@ module AbstractController
       #
       # If the specified layout is a:
       # String:: the String is the template name
-      # Symbol:: call the method specified by the symbol, which will return
-      #   the template name
+      # Symbol:: call the method specified by the symbol, which will return the template name
       # false::  There is no layout
       # true::   raise an ArgumentError
       #
diff --git a/actionpack/lib/action_controller/metal/mime_responds.rb b/actionpack/lib/action_controller/metal/mime_responds.rb
index 41809cf6a1..73e044a092 100644
--- a/actionpack/lib/action_controller/metal/mime_responds.rb
+++ b/actionpack/lib/action_controller/metal/mime_responds.rb
@@ -283,7 +283,30 @@ module ActionController #:nodoc:
       end
     end
 
-    class Collector #:nodoc:
+    # A container of responses available for requests with different mime-types
+    # sent to the current controller action.
+    #
+    # The public controller methods +respond_with+ and +respond_to+ may be called
+    # with a block that is used to define responses to different mime-types, e.g.
+    # for +respond_to+ :
+    #
+    #   respond_to do |format|
+    #     format.html
+    #     format.xml { render :xml => @people.to_xml }
+    #   end
+    #
+    # In this usage, the argument passed to the block (+format+ above) is an
+    # instance of the ActionController::MimeResponds::Collector class. This
+    # object serves as a container in which available responses can be stored by
+    # calling any of the dynamically generated, mime-type-specific methods such
+    # as +html+, +xml+ etc on the Collector. Each response is represented by a
+    # corresponding block if present.
+    #
+    # A subsequent call to #negotiate_format(request) will enable the Collector
+    # to determine which specific mime-type it should respond with for the current
+    # request, with this response then being accessible by calling #response.
+    #
+    class Collector
       include AbstractController::Collector
       attr_accessor :order, :format
 
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 835111eb95..43d5cf1471 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -16,17 +16,28 @@ module ActionView
     # Form helpers are designed to make working with resources much easier
     # compared to using vanilla HTML.
     #
-    # Forms for models are created with +form_for+. That method yields a form
-    # builder that knows the model the form is about. The form builder is thus
-    # able to generate default values for input fields that correspond to model
-    # attributes, and also convenient names, IDs, endpoints, etc.
+    # Typically, a form designed to create or update a resource reflects the
+    # identity of the resource in several ways: (i) the url that the form is
+    # sent to (the form element's +action+ attribute) should result in a request
+    # being routed to the appropriate controller action (with the appropriate <tt>:id</tt>
+    # parameter in the case of an existing resource), (ii) input fields should
+    # be named in such a way that in the controller their values appear in the
+    # appropriate places within the +params+ hash, and (iii) for an existing record, 
+    # when the form is initially displayed, input fields corresponding to attributes
+    # of the resource should show the current values of those attributes.
     #
-    # Conventions in the generated field names allow controllers to receive form
-    # data nicely structured in +params+ with no effort on your side.
+    # In Rails, this is usually achieved by creating the form using +form_for+ and
+    # a number of related helper methods. +form_for+ generates an appropriate <tt>form</tt>
+    # tag and yields a form builder object that knows the model the form is about.
+    # Input fields are created by calling methods defined on the form builder, which
+    # means they are able to generate the appropriate names and default values
+    # corresponding to the model attributes, as well as convenient IDs, etc.
+    # Conventions in the generated field names allow controllers to receive form data
+    # nicely structured in +params+ with no effort on your side.
     #
     # For example, to create a new person you typically set up a new instance of
     # +Person+ in the <tt>PeopleController#new</tt> action, <tt>@person</tt>, and
-    # pass it to +form_for+:
+    # in the view template pass that object to +form_for+:
     #
     #   <%= form_for @person do |f| %>
     #     <%= f.label :first_name %>:
@@ -109,29 +120,14 @@ module ActionView
         object.respond_to?(:to_model) ? object.to_model : object
       end
 
-      # Creates a form and a scope around a specific model object that is used
-      # as a base for questioning about values for the fields.
+      # Creates a form that allows the user to create or update the attributes
+      # of a specific model object.
       #
-      # Rails provides succinct resource-oriented form generation with +form_for+
-      # like this:
-      #
-      #   <%= form_for @offer do |f| %>
-      #     <%= f.label :version, 'Version' %>:
-      #     <%= f.text_field :version %><br />
-      #     <%= f.label :author, 'Author' %>:
-      #     <%= f.text_field :author %><br />
-      #     <%= f.submit %>
-      #   <% end %>
-      #
-      # There, +form_for+ is able to generate the rest of RESTful form
-      # parameters based on introspection on the record, but to understand what
-      # it does we need to dig first into the alternative generic usage it is
-      # based upon.
-      #
-      # === Generic form_for
-      #
-      # The generic way to call +form_for+ yields a form builder around a
-      # model:
+      # The method can be used in several slightly different ways, depending on
+      # how much you wish to rely on Rails to infer automatically from the model
+      # how the form should be constructed. For a generic model object, a form
+      # can be created by passing +form_for+ a string or symbol representing
+      # the object we are concerned with:
       #
       #   <%= form_for :person do |f| %>
       #     First name: <%= f.text_field :first_name %><br />
@@ -141,24 +137,39 @@ module ActionView
       #     <%= f.submit %>
       #   <% end %>
       #
-      # There, the argument is a symbol or string with the name of the
-      # object the form is about.
-      #
-      # The form builder acts as a regular form helper that somehow carries the
-      # model. Thus, the idea is that
+      # The variable +f+ yielded to the block is a FormBuilder object that
+      # incorporates the knowledge about the model object represented by
+      # <tt>:person</tt> passed to +form_for+. Methods defined on the FormBuilder
+      # are used to generate fields bound to this model. Thus, for example,
       #
       #   <%= f.text_field :first_name %>
       #
-      # gets expanded to
+      # will get expanded to
       #
       #   <%= text_field :person, :first_name %>
+      # which results in an html <tt><input></tt> tag whose +name+ attribute is
+      # <tt>person[first_name]</tt>. This means that when the form is submitted,
+      # the value entered by the user will be available in the controller as
+      # <tt>params[:person][:first_name]</tt>.
+      #
+      # For fields generated in this way using the FormBuilder,
+      # if <tt>:person</tt> also happens to be the name of an instance variable
+      # <tt>@person</tt>, the default value of the field shown when the form is
+      # initially displayed (e.g. in the situation where you are editing an
+      # existing record) will be the value of the corresponding attribute of 
+      # <tt>@person</tt>.
       #
       # The rightmost argument to +form_for+ is an
-      # optional hash of options:
-      #
-      # * <tt>:url</tt> - The URL the form is submitted to. It takes the same
-      #   fields you pass to +url_for+ or +link_to+. In particular you may pass
-      #   here a named route directly as well. Defaults to the current action.
+      # optional hash of options -
+      #
+      # * <tt>:url</tt> - The URL the form is to be submitted to. This may be
+      #   represented in the same way as values passed to +url_for+ or +link_to+.
+      #   So for example you may use a named route directly. When the model is
+      #   represented by a string or symbol, as in the example above, if the
+      #   <tt>:url</tt> option is not specified, by default the form will be
+      #   sent back to the current url (We will describe below an alternative
+      #   resource-oriented usage of +form_for+ in which the URL does not need
+      #   to be specified explicitly).
       # * <tt>:namespace</tt> - A namespace for your form to ensure uniqueness of
       #   id attributes on form elements. The namespace attribute will be prefixed
       #   with underscore on the generated HTML id.
@@ -168,7 +179,7 @@ module ActionView
       # possible to use both the stand-alone FormHelper methods and methods
       # from FormTagHelper. For example:
       #
-      #   <%= form_for @person do |f| %>
+      #   <%= form_for :person do |f| %>
       #     First name: <%= f.text_field :first_name %>
       #     Last name : <%= f.text_field :last_name %>
       #     Biography : <%= text_area :person, :biography %>
@@ -180,26 +191,65 @@ module ActionView
       # are designed to work with an object as base, like
       # FormOptionHelper#collection_select and DateHelper#datetime_select.
       #
-      # === Resource-oriented style
+      # === #form_for with a model object
       #
-      # As we said above, in addition to manually configuring the +form_for+
-      # call, you can rely on automated resource identification, which will use
-      # the conventions and named routes of that approach. This is the
-      # preferred way to use +form_for+ nowadays.
+      # In the examples above, the object to be created or edited was
+      # represented by a symbol passed to +form_for+, and we noted that
+      # a string can also be used equivalently. It is also possible, however,
+      # to pass a model object itself to +form_for+. For example, if <tt>@post</tt>
+      # is an existing record you wish to edit, you can create the form using
+      #
+      #   <%= form_for @post do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # This behaves in almost the same way as outlined previously, with a
+      # couple of small exceptions. First, the prefix used to name the input
+      # elements within the form (hence the key that denotes them in the +params+
+      # hash) is actually derived from the object's _class_, e.g. <tt>params[:post]</tt>
+      # if the object's class is +Post+. However, this can be overwritten using
+      # the <tt>:as</tt> option, e.g. -
+      #
+      #   <%= form_for(@person, :as => :client) do |f| %>
+      #     ...
+      #   <% end %>
       #
-      # For example, if <tt>@post</tt> is an existing record you want to edit
+      # would result in <tt>params[:client]</tt>.
+      #
+      # Secondly, the field values shown when the form is initially displayed
+      # are taken from the attributes of the object passed to +form_for+,
+      # regardless of whether the object is an instance
+      # variable. So, for example, if we had a _local_ variable +post+
+      # representing an existing record,
+      #
+      #   <%= form_for post do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # would produce a form with fields whose initial state reflect the current
+      # values of the attributes of +post+.
+      #
+      # === Resource-oriented style
+      #
+      # In the examples just shown, although not indicated explicitly, we still
+      # need to use the <tt>:url</tt> option in order to specify where the
+      # form is going to be sent. However, further simplification is possible
+      # if the record passed to +form_for+ is a _resource_, i.e. it corresponds
+      # to a set of RESTful routes, e.g. defined using the +resources+ method
+      # in <tt>config/routes.rb</tt>. In this case Rails will simply infer the
+      # appropriate URL from the record itself. For example,
       #
       #   <%= form_for @post do |f| %>
       #     ...
       #   <% end %>
       #
-      # is equivalent to something like:
+      # is then equivalent to something like:
       #
       #   <%= form_for @post, :as => :post, :url => post_path(@post), :method => :put, :html => { :class => "edit_post", :id => "edit_post_45" } do |f| %>
       #     ...
       #   <% end %>
       #
-      # And for new records
+      # And for a new record
       #
       #   <%= form_for(Post.new) do |f| %>
       #     ...
@@ -211,7 +261,7 @@ module ActionView
       #     ...
       #   <% end %>
       #
-      # You can also overwrite the individual conventions, like this:
+      # However you can still overwrite individual conventions, such as:
       #
       #   <%= form_for(@post, :url => super_posts_path) do |f| %>
       #     ...
@@ -223,13 +273,6 @@ module ActionView
       #     ...
       #   <% end %>
       #
-      # If you have an object that needs to be represented as a different
-      # parameter, like a Person that acts as a Client:
-      #
-      #   <%= form_for(@person, :as => :client) do |f| %>
-      #     ...
-      #   <% end %>
-      #
       # For namespaced routes, like +admin_post_url+:
       #
       #   <%= form_for([:admin, @post]) do |f| %>
@@ -252,9 +295,9 @@ module ActionView
       #
       #    :method => (:get|:post|:patch|:put|:delete)
       #
-      # in the options hash. If the verb is not GET or POST, which are natively supported by HTML forms, the
-      # form will be set to POST and a hidden input called _method will carry the intended verb for the server
-      # to interpret.
+      # in the options hash. If the verb is not GET or POST, which are natively
+      # supported by HTML forms, the form will be set to POST and a hidden input
+      # called _method will carry the intended verb for the server to interpret.
       #
       # === Unobtrusive JavaScript
       #
@@ -402,30 +445,59 @@ module ActionView
       #
       # === Generic Examples
       #
+      # Although the usage and purpose of +field_for+ is similar to +form_for+'s,
+      # its method signature is slightly different. Like +form_for+, it yields
+      # a FormBuilder object associated with a particular model object to a block,
+      # and within the block allows methods to be called on the builder to
+      # generate fields associated with the model object. Fields may reflect
+      # a model object in two ways - how they are named (hence how submitted
+      # values appear within the +params+ hash in the controller) and what
+      # default values are shown when the form the fields appear in is first
+      # displayed. In order for both of these features to be specified independently,
+      # both an object name (represented by either a symbol or string) and the
+      # object itself can be passed to the method separately -
+      #
       #   <%= form_for @person do |person_form| %>
       #     First name: <%= person_form.text_field :first_name %>
       #     Last name : <%= person_form.text_field :last_name %>
       #
-      #     <%= fields_for @person.permission do |permission_fields| %>
+      #     <%= fields_for :permission, @person.permission do |permission_fields| %>
       #       Admin?  : <%= permission_fields.check_box :admin %>
       #     <% end %>
       #
       #     <%= f.submit %>
       #   <% end %>
       #
-      # ...or if you have an object that needs to be represented as a different
-      # parameter, like a Client that acts as a Person:
+      # In this case, the checkbox field will be represented by an HTML +input+
+      # tag with the +name+ attribute <tt>permission[admin]</tt>, and the submitted
+      # value will appear in the controller as <tt>params[:permission][:admin]</tt>.
+      # If <tt>@person.permission</tt> is an existing record with an attribute
+      # +admin+, the initial state of the checkbox when first displayed will
+      # reflect the value of <tt>@person.permission.admin</tt>.
+      #
+      # Often this can be simplified by passing just the name of the model
+      # object to +fields_for+ -
       #
-      #   <%= fields_for :person, @client do |permission_fields| %>
+      #   <%= fields_for :permission do |permission_fields| %>
       #     Admin?: <%= permission_fields.check_box :admin %>
       #   <% end %>
       #
-      # ...or if you don't have an object, just a name of the parameter:
+      # ...in which case, if <tt>:permission</tt> also happens to be the name of an
+      # instance variable <tt>@permission</tt>, the initial state of the input
+      # field will reflect the value of that variable's attribute <tt>@permission.admin</tt>.
       #
-      #   <%= fields_for :person do |permission_fields| %>
+      # Alternatively, you can pass just the model object itself (if the first
+      # argument isn't a string or symbol +fields_for+ will realize that the
+      # name has been omitted) -
+      #
+      #   <%= fields_for @person.permission do |permission_fields| %>
       #     Admin?: <%= permission_fields.check_box :admin %>
       #   <% end %>
       #
+      # and +fields_for+ will derive the required name of the field from the
+      # _class_ of the model object, e.g. if <tt>@person.permission</tt>, is
+      # of class +Permission+, the field will still be named <tt>permission[admin]</tt>.
+      #
       # Note: This also works for the methods in FormOptionHelper and
       # DateHelper that are designed to work with an object as base, like
       # FormOptionHelper#collection_select and DateHelper#datetime_select.
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index b1a5110e2d..b901f06ca4 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -1382,7 +1382,9 @@ module ActiveRecord
       #   and +decrement_counter+. The counter cache is incremented when an object of this
       #   class is created and decremented when it's destroyed. This requires that a column
       #   named <tt>#{table_name}_count</tt> (such as +comments_count+ for a belonging Comment class)
-      #   is used on the associate class (such as a Post class). You can also specify a custom counter
+      #   is used on the associate class (such as a Post class) - that is the migration for 
+      #   <tt>#{table_name}_count</tt> is created on the associate class (such that Post.comments_count will
+      #   return the count cached, see note below). You can also specify a custom counter
       #   cache column by providing a column name instead of a +true+/+false+ value to this
       #   option (e.g., <tt>:counter_cache => :my_custom_counter</tt>.)
       #   Note: Specifying a counter cache will add it to that model's list of readonly attributes
diff --git a/railties/guides/code/getting_started/config/initializers/secret_token.rb b/railties/guides/code/getting_started/config/initializers/secret_token.rb
index b0c8ee23c1..f36ebdda18 100644
--- a/railties/guides/code/getting_started/config/initializers/secret_token.rb
+++ b/railties/guides/code/getting_started/config/initializers/secret_token.rb
@@ -4,4 +4,6 @@
 # If you change this key, all old signed cookies will become invalid!
 # Make sure the secret is at least 30 characters and all random,
 # no regular words or you'll be exposed to dictionary attacks.
+# Make sure your secret key is kept private
+# if you're sharing your code publicly.
 Blog::Application.config.secret_token = '685a9bf865b728c6549a191c90851c1b5ec41ecb60b9e94ad79dd3f824749798aa7b5e94431901960bee57809db0947b481570f7f13376b7ca190fa28099c459'
diff --git a/railties/guides/source/2_2_release_notes.textile b/railties/guides/source/2_2_release_notes.textile
index 8e2d528eee..3a0f2efbaf 100644
--- a/railties/guides/source/2_2_release_notes.textile
+++ b/railties/guides/source/2_2_release_notes.textile
@@ -229,7 +229,7 @@ This will enable recognition of (among others) these routes:
 
 * Lead Contributor: "S. Brent Faulkner":http://www.unwwwired.net/
 * More information:
-** "Rails Routing from the Outside In":http://guides.rubyonrails.org/routing.html#_nested_resources
+** "Rails Routing from the Outside In":http://guides.rubyonrails.org/routing.html#nested-resources
 ** "What's New in Edge Rails: Shallow Routes":http://ryandaigle.com/articles/2008/9/7/what-s-new-in-edge-rails-shallow-routes
 
 h4. Method Arrays for Member or Collection Routes
diff --git a/railties/guides/source/action_mailer_basics.textile b/railties/guides/source/action_mailer_basics.textile
index 26c95be031..2760e03be1 100644
--- a/railties/guides/source/action_mailer_basics.textile
+++ b/railties/guides/source/action_mailer_basics.textile
@@ -244,7 +244,7 @@ It is possible to send email to one or more recipients in one email (for e.g. in
 
 <ruby>
 class AdminMailer < ActionMailer::Base
-  default :to => Admin.all.map(&:email),
+  default :to => Proc.new { Admin.all.map(&:email) },
           :from => "notification@example.com"
 
   def new_registration(user)
diff --git a/railties/guides/source/active_record_validations_callbacks.textile b/railties/guides/source/active_record_validations_callbacks.textile
index 349d02c1f6..88c4481e5e 100644
--- a/railties/guides/source/active_record_validations_callbacks.textile
+++ b/railties/guides/source/active_record_validations_callbacks.textile
@@ -531,7 +531,7 @@ Person.new.valid?  => ActiveModel::StrictValidationFailed: Name can't be blank
 
 h3. Conditional Validation
 
-Sometimes it will make sense to validate an object just when a given predicate is satisfied. You can do that by using the +:if+ and +:unless+ options, which can take a symbol, a string or a +Proc+. You may use the +:if+ option when you want to specify when the validation *should* happen. If you want to specify when the validation *should not* happen, then you may use the +:unless+ option.
+Sometimes it will make sense to validate an object just when a given predicate is satisfied. You can do that by using the +:if+ and +:unless+ options, which can take a symbol, a string, a +Proc+ or an +Array+. You may use the +:if+ option when you want to specify when the validation *should* happen. If you want to specify when the validation *should not* happen, then you may use the +:unless+ option.
 
 h4. Using a Symbol with +:if+ and +:unless+
 
@@ -583,6 +583,20 @@ end
 
 All validations inside of +with_options+ block will have automatically passed the condition +:if => :is_admin?+
 
+h4. Combining validation conditions
+
+On the other hand, when multiple conditions define whether or not a validation should happen, an +Array+ can be used. Moreover, you can apply both +:if:+ and +:unless+ to the same validation.
+
+<ruby>
+class Computer < ActiveRecord::Base
+  validates :mouse, :presence => true,
+                    :if => ["market.retail?", :desktop?]
+                    :unless => Proc.new { |c| c.trackpad.present? }
+end
+</ruby>
+
+The validation only runs when all the +:if+ conditions and none of the +:unless+ conditions are evaluated to +true+.
+
 h3. Performing Custom Validations
 
 When the built-in validation helpers are not enough for your needs, you can write your own validators or validation methods as you prefer.
@@ -1107,7 +1121,7 @@ Post destroyed
 
 h3. Conditional Callbacks
 
-As with validations, we can also make the calling of a callback method conditional on the satisfaction of a given predicate. We can do this using the +:if+ and +:unless+ options, which can take a symbol, a string or a +Proc+. You may use the +:if+ option when you want to specify under which conditions the callback *should* be called. If you want to specify the conditions under which the callback *should not* be called, then you may use the +:unless+ option.
+As with validations, we can also make the calling of a callback method conditional on the satisfaction of a given predicate. We can do this using the +:if+ and +:unless+ options, which can take a symbol, a string, a +Proc+ or an +Array+. You may use the +:if+ option when you want to specify under which conditions the callback *should* be called. If you want to specify the conditions under which the callback *should not* be called, then you may use the +:unless+ option.
 
 h4. Using +:if+ and +:unless+ with a +Symbol+
 
diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index 2091ce0395..5d0a3f82e8 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/railties/guides/source/active_support_core_extensions.textile
@@ -509,55 +509,6 @@ end
 
 NOTE: Defined in +active_support/core_ext/module/aliasing.rb+.
 
-h5. +attr_accessor_with_default+
-
-The method +attr_accessor_with_default+ serves the same purpose as the Ruby macro +attr_accessor+ but allows you to set a default value for the attribute:
-
-<ruby>
-class Url
-  attr_accessor_with_default :port, 80
-end
-
-Url.new.port # => 80
-</ruby>
-
-The default value can be also specified with a block, which is called in the context of the corresponding object:
-
-<ruby>
-class User
-  attr_accessor :name, :surname
-  attr_accessor_with_default(:full_name) do
-    [name, surname].compact.join(" ")
-  end
-end
-
-u = User.new
-u.name = 'Xavier'
-u.surname = 'Noria'
-u.full_name # => "Xavier Noria"
-</ruby>
-
-The result is not cached, the block is invoked in each call to the reader.
-
-You can overwrite the default with the writer:
-
-<ruby>
-url = Url.new
-url.host # => 80
-url.host = 8080
-url.host # => 8080
-</ruby>
-
-The default value is returned as long as the attribute is unset. The reader does not rely on the value of the attribute to know whether it has to return the default. It rather monitors the writer: if there's any assignment the value is no longer considered to be unset.
-
-Active Resource uses this macro to set a default value for the +:primary_key+ attribute:
-
-<ruby>
-attr_accessor_with_default :primary_key, 'id'
-</ruby>
-
-NOTE: Defined in +active_support/core_ext/module/attr_accessor_with_default.rb+.
-
 h5. Internal Attributes
 
 When you are defining an attribute in a class that is meant to be subclassed, name collisions are a risk. That's remarkably important for libraries.
diff --git a/railties/guides/source/active_support_instrumentation.textile b/railties/guides/source/active_support_instrumentation.textile
index f9452400ad..8e2866dfc3 100644
--- a/railties/guides/source/active_support_instrumentation.textile
+++ b/railties/guides/source/active_support_instrumentation.textile
@@ -21,10 +21,67 @@ You are even able to create your own events inside your application which you ca
 
 h3. Rails framework hooks
 
+Within the Ruby on Rails framework, there are a number of hooks provided for common events. These are detailed below.
+
 h4. Action Mailer
 
+h5. receive.action_mailer
+
+This hook is called when the +receive+ method of an +ActionMailer::Base+ class is called:
+
+<ruby>
+  class Mailer < ActionMailer::Base
+    def receive(mail)
+
+    end
+  end
+</ruby>
+
+The payload for this event has the following parameters related to the incoming email:
+
+|_.Key       |_.Value|
+|mailer      |Name of the mailer class|
+|message_id  |ID of the message, generated by the Mail gem|
+|subject     |Subject of the mail|
+|to          |To address(es) of the mail|
+|from        |From address of the mail|
+|bcc         |BCC addresses of the mail|
+|cc          |CC addresses of the mail|
+|date        |Date of the mail|
+|mail        |The encoded form of the mail|
+
+h5. deliver.action_mailer
+
+This hook is called when the +deliver+ method is called on a +Mail::Message+ object. This is due to a hook inserted by Action Mailer, rather than a specific feature of the Mail gem itself.
+
+The payload for this event has the following parameters related to the outgoing email:
+
+|_.Key       |_.Value|
+|mailer      |Name of the mailer class|
+|message_id  |ID of the message, generated by the Mail gem|
+|subject     |Subject of the mail|
+|to          |To address(es) of the mail|
+|from        |From address of the mail|
+|bcc         |BCC addresses of the mail|
+|cc          |CC addresses of the mail|
+|date        |Date of the mail|
+|mail        |The encoded form of the mail|
+
+
 h4. Action Controller
 
+h5. write_fragment.action_controller
+
+h5. read_fragment.action_controller
+
+h5. exist_fragment?.action_controller
+
+h5. expire_fragment.action_controller
+
+h5. write_page.action_controller
+
+h5. expire_page.action_controller
+
 h4. Action View
 
 h4. Active Record
diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile
index ba92aedbd0..493b7c30be 100644
--- a/railties/guides/source/association_basics.textile
+++ b/railties/guides/source/association_basics.textile
@@ -1322,7 +1322,7 @@ If you need to evaluate conditions dynamically at runtime, use a proc:
 <ruby>
 class Customer < ActiveRecord::Base
   has_many :latest_orders, :class_name => "Order",
-    :conditions => proc { ["orders.created_at > ?, 10.hours.ago] }
+    :conditions => proc { ["orders.created_at > ?", 10.hours.ago] }
 end
 </ruby>
 
diff --git a/railties/guides/source/configuring.textile b/railties/guides/source/configuring.textile
index 619c0ae16c..d6e500fc4b 100644
--- a/railties/guides/source/configuring.textile
+++ b/railties/guides/source/configuring.textile
@@ -294,6 +294,8 @@ h4. Configuring Active Record
 
 * +config.active_record.dependent_restrict_raises+ will control the behavior when an object with a <tt>:dependent => :restrict</tt> association is deleted. Setting this to false will prevent +DeleteRestrictionError+ from being raised and instead will add an error on the model object. Defaults to false in the development mode.
 
+* +config.active_record.mass_assignment_sanitizer+ will determine the strictness of the mass assignment sanitization within Rails. Defaults to +:strict+. In this mode, mass assigning any non-+attr_accessible+ attribute in a +create+ or +update_attributes+ call will raise an exception. Setting this option to +:logger+ will only print to the log file when an attribute is being assigned and will not raise an exception.
+
 The MySQL adapter adds one additional configuration option:
 
 * +ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans+ controls whether Active Record will consider all +tinyint(1)+ columns in a MySQL database to be booleans and is true by default.
diff --git a/railties/guides/source/contributing_to_ruby_on_rails.textile b/railties/guides/source/contributing_to_ruby_on_rails.textile
index e082fd2941..df8b16eb9e 100644
--- a/railties/guides/source/contributing_to_ruby_on_rails.textile
+++ b/railties/guides/source/contributing_to_ruby_on_rails.textile
@@ -332,6 +332,8 @@ When you're happy with the code on your computer, you need to commit the changes
 $ git commit -a -m "Here is a commit message on what I changed in this commit"
 </shell>
 
+TIP. Please squash your commits into a single commit when appropriate. This simplifies future cherry picks, and also keeps the git log clean. 
+
 h4. Update master
 
 It’s pretty likely that other changes to master have happened while you were working. Go get them:
diff --git a/railties/guides/source/documents.yaml b/railties/guides/source/documents.yaml
index 08aafda288..2acdcca39c 100644
--- a/railties/guides/source/documents.yaml
+++ b/railties/guides/source/documents.yaml
@@ -97,6 +97,11 @@
       url: asset_pipeline.html
       description: This guide documents the asset pipeline.
     - 
+      name: Getting Started with Engines
+      url: engines.html
+      description: This guide explains how to write a mountable engine.
+      work_in_progress: true
+    - 
       name: The Rails Initialization Process
       work_in_progress: true
       url: initialization.html
diff --git a/railties/guides/source/form_helpers.textile b/railties/guides/source/form_helpers.textile
index 6d9cd5440b..8934667c5e 100644
--- a/railties/guides/source/form_helpers.textile
+++ b/railties/guides/source/form_helpers.textile
@@ -39,7 +39,7 @@ When called without arguments like this, it creates a +&lt;form&gt;+ tag which,
 </form>
 </html>
 
-Now, you'll notice that the HTML contains something extra: a +div+ element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name +utf8+ enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are "GET" or "POST". The second input element with name +authenticity_token+ is a security feature of Rails called *cross-site request forgery protection*, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the "Security Guide":./security.html#_cross_site_reference_forgery_csrf.
+Now, you'll notice that the HTML contains something extra: a +div+ element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name +utf8+ enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are "GET" or "POST". The second input element with name +authenticity_token+ is a security feature of Rails called *cross-site request forgery protection*, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the "Security Guide":./security.html#cross-site-request-forgery-csrf.
 
 NOTE: Throughout this guide, the +div+ with the hidden input elements will be excluded from code samples for brevity.
 
@@ -428,7 +428,7 @@ As with other helpers, if you were to use the +select+ helper on a form builder
 <%= f.select(:city_id, ...) %>
 </erb>
 
-WARNING: If you are using +select+ (or similar helpers such as +collection_select+, +select_tag+) to set a +belongs_to+ association you must pass the name of the foreign key (in the example above +city_id+), not the name of association itself. If you specify +city+ instead of +city_id+ Active Record will raise an error along the lines of <tt> ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) </tt> when you pass the +params+ hash to +Person.new+ or +update_attributes+. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. You may wish to consider the use of +attr_protected+ and +attr_accessible+. For further details on this, see the "Ruby On Rails Security Guide":security.html#_mass_assignment.
+WARNING: If you are using +select+ (or similar helpers such as +collection_select+, +select_tag+) to set a +belongs_to+ association you must pass the name of the foreign key (in the example above +city_id+), not the name of association itself. If you specify +city+ instead of +city_id+ Active Record will raise an error along the lines of <tt> ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) </tt> when you pass the +params+ hash to +Person.new+ or +update_attributes+. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. You may wish to consider the use of +attr_protected+ and +attr_accessible+. For further details on this, see the "Ruby On Rails Security Guide":security.html#mass-assignment.
 
 h4. Option Tags from a Collection of Arbitrary Objects
 
diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile
index b1a09c0c05..747a4d6791 100644
--- a/railties/guides/source/security.textile
+++ b/railties/guides/source/security.textile
@@ -374,7 +374,7 @@ end
 Mass-assignment saves you much work, because you don't have to set each value individually. Simply pass a hash to the +new+ method, or +assign_attributes=+ a hash value, to set the model's attributes to the values in the hash. The problem is that it is often used in conjunction with the parameters (params) hash available in the controller, which may be manipulated by an attacker. He may do so by changing the URL like this:
 
 <pre>
-"name":http://www.example.com/user/signup?user[name]=ow3ned&user[admin]=1
+http://www.example.com/user/signup?user[name]=ow3ned&user[admin]=1
 </pre>
 
 This will set the following parameters in the controller:
diff --git a/railties/lib/rails/generators/rails/app/templates/config/initializers/secret_token.rb.tt b/railties/lib/rails/generators/rails/app/templates/config/initializers/secret_token.rb.tt
index a3143f1346..e02397aaf9 100644
--- a/railties/lib/rails/generators/rails/app/templates/config/initializers/secret_token.rb.tt
+++ b/railties/lib/rails/generators/rails/app/templates/config/initializers/secret_token.rb.tt
@@ -4,4 +4,6 @@
 # If you change this key, all old signed cookies will become invalid!
 # Make sure the secret is at least 30 characters and all random,
 # no regular words or you'll be exposed to dictionary attacks.
+# Make sure your secret_token is kept private
+# if you're sharing your code publicly.
 <%= app_const %>.config.secret_token = '<%= app_secret %>'