17 files changed, 51 insertions, 41 deletions

diff --git a/guides/assets/images/icons/README b/guides/assets/images/icons/README
index f12b2a730c..09da77fc86 100644
--- a/guides/assets/images/icons/README
+++ b/guides/assets/images/icons/README
@@ -1,5 +1,5 @@
 Replaced the plain DocBook XSL admonition icons with Jimmac's DocBook
 icons (http://jimmac.musichall.cz/ikony.php3). I dropped transparency
-from the Jimmac icons to get round MS IE and FOP PNG incompatibilies.
+from the Jimmac icons to get round MS IE and FOP PNG incompatibilities.
 
 Stuart Rackham
diff --git a/guides/source/3_0_release_notes.md b/guides/source/3_0_release_notes.md
index ebe8847168..d398cd680c 100644
--- a/guides/source/3_0_release_notes.md
+++ b/guides/source/3_0_release_notes.md
@@ -342,7 +342,7 @@ Helpers that do something else, like `cache` or `content_for`, are not affected
 * Helpers now output HTML 5 by default.
 * Form label helper now pulls values from I18n with a single value, so `f.label :name` will pull the `:name` translation.
 * I18n select label on should now be :en.helpers.select instead of :en.support.select.
-* You no longer need to place a minus sign at the end of a ruby interpolation inside an ERb template to remove the trailing carriage return in the HTML output.
+* You no longer need to place a minus sign at the end of a Ruby interpolation inside an ERB template to remove the trailing carriage return in the HTML output.
 * Added `grouped_collection_select` helper to Action View.
 * `content_for?` has been added allowing you to check for the existence of content in a view before rendering.
 * passing `:value => nil` to form helpers will set the field's `value` attribute to nil as opposed to using the default value
@@ -611,4 +611,3 @@ Credits
 See the [full list of contributors to Rails](http://contributors.rubyonrails.org/) for the many people who spent many hours making Rails 3. Kudos to all of them.
 
 Rails 3.0 Release Notes were compiled by [Mikel Lindsaar](http://lindsaar.net.)
-
diff --git a/guides/source/4_0_release_notes.md b/guides/source/4_0_release_notes.md
index 5f2d994dd2..b9dbe820c8 100644
--- a/guides/source/4_0_release_notes.md
+++ b/guides/source/4_0_release_notes.md
@@ -85,7 +85,7 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railt
 
 *   New test locations `test/models`, `test/helpers`, `test/controllers`, and `test/mailers`. Corresponding rake tasks added as well. ([Pull Request](https://github.com/rails/rails/pull/7878))
 
-* Your app's executables now live in the `bin/` dir. Run `rake rails:update:bin` to get `bin/bundle`, `bin/rails`, and `bin/rake`.
+* Your app's executables now live in the `bin/` directory. Run `rake rails:update:bin` to get `bin/bundle`, `bin/rails`, and `bin/rake`.
 
 * Threadsafe on by default
 
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 43a59e8d43..28939f307f 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -568,10 +568,10 @@ end
 
 Note that while for session values you set the key to `nil`, to delete a cookie value you should use `cookies.delete(:key)`.
 
-Rendering xml and json data
+Rendering XML and JSON data
 ---------------------------
 
-ActionController makes it extremely easy to render `xml` or `json` data. If you've generated a controller using scaffolding, it would look something like this:
+ActionController makes it extremely easy to render `XML` or `JSON` data. If you've generated a controller using scaffolding, it would look something like this:
 
 ```ruby
 class UsersController < ApplicationController
diff --git a/guides/source/active_model_basics.md b/guides/source/active_model_basics.md
index 68ac26c681..1d87646e49 100644
--- a/guides/source/active_model_basics.md
+++ b/guides/source/active_model_basics.md
@@ -14,7 +14,7 @@ Active Model is a library containing various modules used in developing framewor
 
 ### AttributeMethods
 
-The AttributeMethods module can add custom prefixes and suffixes on methods of a class. It is used by defining the prefixes and suffixes, which methods on the object will use them.
+The AttributeMethods module can add custom prefixes and suffixes on methods of a class. It is used by defining the prefixes and suffixes and which methods on the object will use them.
 
 ```ruby
 class Person
@@ -45,7 +45,7 @@ person.age_highest?  # false
 
 ### Callbacks
 
-Callbacks gives Active Record style callbacks. This provides the ability to define the callbacks and those will run at appropriate time. After defining a callbacks you can wrap with before, after and around custom methods.
+Callbacks gives Active Record style callbacks. This provides an ability to define callbacks which run at appropriate times. After defining callbacks, you can wrap them with before, after and around custom methods.
 
 ```ruby
 class Person
@@ -57,19 +57,19 @@ class Person
 
   def update
     run_callbacks(:update) do
-      # This will call when we are trying to call update on object.
+      # This method is called when update is called on an object.
     end
   end
 
   def reset_me
-    # This method will call when you are calling update on object as a before_update callback as defined.
+    # This method is called when update is called on an object as a before_update callback is defined.
   end
 end
 ```
 
 ### Conversion
 
-If a class defines `persisted?` and `id` methods then you can include `Conversion` module in that class and you can able to call Rails conversion methods to objects of that class.
+If a class defines `persisted?` and `id` methods, then you can include the `Conversion` module in that class and call the Rails conversion methods on objects of that class.
 
 ```ruby
 class Person
diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index 80eec428c1..19b214f114 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -732,7 +732,7 @@ The `reorder` method overrides the default scope order. For example:
 class Post < ActiveRecord::Base
   ..
   ..
-  has_many :comments, order: 'posted_at DESC'
+  has_many :comments, -> { order('posted_at DESC') }
 end
 
 Post.find(10).comments.reorder('name')
diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md
index 6daad33dea..c012ded888 100644
--- a/guides/source/active_support_core_extensions.md
+++ b/guides/source/active_support_core_extensions.md
@@ -166,7 +166,7 @@ NOTE: Defined in `active_support/core_ext/object/duplicable.rb`.
 
 ### `deep_dup`
 
-The `deep_dup` method returns deep copy of a given object. Normally, when you `dup` an object that contains other objects, ruby does not `dup` them, so it creates a shallow copy of the object. If you have an array with a string, for example, it will look like this:
+The `deep_dup` method returns deep copy of a given object. Normally, when you `dup` an object that contains other objects, Ruby does not `dup` them, so it creates a shallow copy of the object. If you have an array with a string, for example, it will look like this:
 
 ```ruby
 array     = ['string']
diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md
index a2849dd98f..b86c7bfc4e 100644
--- a/guides/source/asset_pipeline.md
+++ b/guides/source/asset_pipeline.md
@@ -430,7 +430,7 @@ in scope in development mode regardless of the value of this flag. Changing this
 engines. Engines can define assets for precompilation as well. Since the complete environment is not loaded,
 engines (or other gems) will not be loaded, which can cause missing assets.
 
-Capistrano (v2.8.0 and above) includes a recipe to handle this in deployment. Add the following line to `Capfile`:
+Capistrano (v2.15.1 and above) includes a recipe to handle this in deployment. Add the following line to `Capfile`:
 
 ```ruby
 load 'deploy/assets'
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index 8d203d265a..16a5241319 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -693,6 +693,17 @@ There are a few limitations to `inverse_of` support:
 * They do not work with `:as` associations.
 * For `belongs_to` associations, `has_many` inverse associations are ignored.
 
+Every association will attempt to automatically find the inverse association
+and set the `:inverse_of` option heuristically (based on the association name).
+Most associations with standard names will be supported. However, associations
+that contain the following options will not have their inverses set
+automatically:
+
+* :conditions
+* :through
+* :polymorphic
+* :foreign_key
+
 Detailed Association Reference
 ------------------------------
 
diff --git a/guides/source/credits.html.erb b/guides/source/credits.html.erb
index 74ae7216e1..10dd8178fb 100644
--- a/guides/source/credits.html.erb
+++ b/guides/source/credits.html.erb
@@ -40,7 +40,7 @@ Oscar Del Ben is a software engineer at <a href="http://www.wildfireapp.com/">Wi
 <% end %>
 
 <%= author('Tore Darell', 'toretore') do %>
-  Tore Darell is an independent developer based in Menton, France who specialises in cruft-free web applications using Ruby, Rails and unobtrusive JavaScript. His home on the internet is his blog <a href="http://tore.darell.no">Sneaky Abstractions</a>.
+  Tore Darell is an independent developer based in Menton, France who specialises in cruft-free web applications using Ruby, Rails and unobtrusive JavaScript. His home on the Internet is his blog <a href="http://tore.darell.no">Sneaky Abstractions</a>.
 <% end %>
 
 <%= author('Jeff Dean', 'zilkey') do %>
diff --git a/guides/source/development_dependencies_install.md b/guides/source/development_dependencies_install.md
index ef622103f4..5647a4c1b7 100644
--- a/guides/source/development_dependencies_install.md
+++ b/guides/source/development_dependencies_install.md
@@ -5,6 +5,10 @@ This guide covers how to setup an environment for Ruby on Rails core development
 
 After reading this guide, you will know:
 
+* How to set up your machine for Rails development
+* How to run specific groups of unit tests from the Rails test suite
+* How the ActiveRecord portion of the Rails test suite operates
+
 --------------------------------------------------------------------------------
 
 The Easy Way
@@ -53,7 +57,7 @@ If you are on Fedora or CentOS, you can run
 $ sudo yum install libxml2 libxml2-devel libxslt libxslt-devel
 ```
 
-If you have any problems with these libraries, you should install them manually compiling the source code. Just follow the instructions at the [Red Hat/CentOS section of the Nokogiri tutorials](http://nokogiri.org/tutorials/installing_nokogiri.html#red_hat__centos) .
+If you have any problems with these libraries, you can install them manually by compiling the source code. Just follow the instructions at the [Red Hat/CentOS section of the Nokogiri tutorials](http://nokogiri.org/tutorials/installing_nokogiri.html#red_hat__centos) .
 
 Also, SQLite3 and its development files for the `sqlite3-ruby` gem — in Ubuntu you're done with just
 
@@ -93,7 +97,7 @@ $ cd actionpack
 $ bundle exec rake test
 ```
 
-If you want to run the tests located in a specific directory use the `TEST_DIR` environment variable. For example, this will run the tests of the `railties/test/generators` directory only:
+If you want to run the tests located in a specific directory use the `TEST_DIR` environment variable. For example, this will run the tests in the `railties/test/generators` directory only:
 
 ```bash
 $ cd railties
@@ -133,14 +137,14 @@ $ sudo yum install mysql-server mysql-devel
 $ sudo yum install postgresql-server postgresql-devel
 ```
 
-After that run:
+After that, run:
 
 ```bash
 $ rm .bundle/config
 $ bundle install
 ```
 
-We need first to delete `.bundle/config` because Bundler remembers in that file that we didn't want to install the "db" group (alternatively you can edit the file).
+First, we need to delete `.bundle/config` because Bundler remembers in that file that we didn't want to install the "db" group (alternatively you can edit the file).
 
 In order to be able to run the test suite against MySQL you need to create a user named `rails` with privileges on the test databases:
 
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md
index 46115afb8c..599e47949d 100644
--- a/guides/source/getting_started.md
+++ b/guides/source/getting_started.md
@@ -29,7 +29,7 @@ prerequisites installed:
 Rails is a web application framework running on the Ruby programming language.
 If you have no prior experience with Ruby, you will find a very steep learning
 curve diving straight into Rails. There are some good free resources on the
-internet for learning Ruby, including:
+Internet for learning Ruby, including:
 
 * [Mr. Neighborly's Humble Little Ruby Book](http://www.humblelittlerubybook.com)
 * [Programming Ruby](http://www.ruby-doc.org/docs/ProgrammingRuby/)
@@ -853,8 +853,7 @@ it look as follows:
 ```html+erb
 <h1>Editing post</h1>
 
-<%= form_for :post, url: post_path(@post.id) },
-method: :patch do |f| %>
+<%= form_for :post, url: post_path(@post.id), method: :patch do |f| %>
   <% if @post.errors.any? %>
   <div id="errorExplanation">
     <h2><%= pluralize(@post.errors.count, "error") %> prohibited
@@ -934,7 +933,7 @@ appear next to the "Show" link:
   <tr>
     <td><%= post.title %></td>
     <td><%= post.text %></td>
-    <td><%= link_to 'Show', post_path %></td>
+    <td><%= link_to 'Show', post_path(post) %></td>
     <td><%= link_to 'Edit', edit_post_path(post) %></td>
   </tr>
 <% end %>
@@ -1076,7 +1075,7 @@ together.
   <tr>
     <td><%= post.title %></td>
     <td><%= post.text %></td>
-    <td><%= link_to 'Show', post_path %></td>
+    <td><%= link_to 'Show', post_path(post) %></td>
     <td><%= link_to 'Edit', edit_post_path(post) %></td>
     <td><%= link_to 'Destroy', post_path(post),
                     method: :delete, data: { confirm: 'Are you sure?' } %></td>
@@ -1149,19 +1148,17 @@ class CreateComments < ActiveRecord::Migration
     create_table :comments do |t|
       t.string :commenter
       t.text :body
-      t.references :post
+      t.references :post, index: true
 
       t.timestamps
     end
-
-    add_index :comments, :post_id
   end
 end
 ```
 
 The `t.references` line sets up a foreign key column for the association between
-the two models. And the `add_index` line sets up an index for this association
-column. Go ahead and run the migration:
+the two models. An index for this association is also created on this column.
+Go ahead and run the migration:
 
 ```bash
 $ rake db:migrate
@@ -1173,10 +1170,8 @@ run against the current database, so in this case you will just see:
 ```bash
 ==  CreateComments: migrating =================================================
 -- create_table(:comments)
-   -> 0.0008s
--- add_index(:comments, :post_id)
-   -> 0.0003s
-==  CreateComments: migrated (0.0012s) ========================================
+   -> 0.0115s
+==  CreateComments: migrated (0.0119s) ========================================
 ```
 
 ### Associating Models
diff --git a/guides/source/initialization.md b/guides/source/initialization.md
index 72d56b7feb..9fcd530183 100644
--- a/guides/source/initialization.md
+++ b/guides/source/initialization.md
@@ -114,7 +114,7 @@ If we used `s` rather than `server`, Rails will use the `aliases` defined in the
 
 ```ruby
 when 'server'
-  # Change to the application's path if there is no config.ru file in current dir.
+  # Change to the application's path if there is no config.ru file in current directory.
   # This allows us to run `rails server` from other directories, but still get
   # the main config.ru and properly set the tmp directory.
   Dir.chdir(File.expand_path('../../', APP_PATH)) unless File.exists?(File.expand_path("config.ru"))
diff --git a/guides/source/migrations.md b/guides/source/migrations.md
index 9c92efd521..fcfc54a3d7 100644
--- a/guides/source/migrations.md
+++ b/guides/source/migrations.md
@@ -852,7 +852,7 @@ end
 # app/models/product.rb
 
 class Product < ActiveRecord::Base
-  validates :flag, presence: true
+  validates :flag, :inclusion => { :in => [true, false] }
 end
 ```
 
@@ -877,7 +877,8 @@ end
 # app/models/product.rb
 
 class Product < ActiveRecord::Base
-  validates :flag, :fuzz, presence: true
+  validates :flag, :inclusion => { :in => [true, false] }
+  validates :fuzz, presence: true
 end
 ```
 
diff --git a/guides/source/routing.md b/guides/source/routing.md
index f4cb8fe15b..c26a827172 100644
--- a/guides/source/routing.md
+++ b/guides/source/routing.md
@@ -857,7 +857,7 @@ resources :user_permissions, controller: 'admin/user_permissions'
 This will route to the `Admin::UserPermissions` controller.
 
 NOTE: Only the directory notation is supported. Specifying the
-controller with ruby constant notation (eg. `:controller =>
+controller with Ruby constant notation (eg. `:controller =>
 'Admin::UserPermissions'`) can lead to routing problems and results in
 a warning.
 
diff --git a/guides/source/security.md b/guides/source/security.md
index b2d09369e2..f04129acdb 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -58,7 +58,7 @@ WARNING: _Stealing a user's session id lets an attacker use the web application
 
 Many web applications have an authentication system: a user provides a user name and password, the web application checks them and stores the corresponding user id in the session hash. From now on, the session is valid. On every request the application will load the user, identified by the user id in the session, without the need for new authentication. The session id in the cookie identifies the session.
 
-Hence, the cookie serves as temporary authentication for the web application. Everyone who seizes a cookie from someone else, may use the web application as this user – with possibly severe consequences. Here are some ways to hijack a session, and their countermeasures:
+Hence, the cookie serves as temporary authentication for the web application. Anyone who seizes a cookie from someone else, may use the web application as this user – with possibly severe consequences. Here are some ways to hijack a session, and their countermeasures:
 
 * Sniff the cookie in an insecure network. A wireless LAN can be an example of such a network. In an unencrypted wireless LAN it is especially easy to listen to the traffic of all connected clients. This is one more reason not to work from a coffee shop. For the web application builder this means to _provide a secure connection over SSL_. In Rails 3.1 and later, this could be accomplished by always forcing SSL connection in your application config file:
 
@@ -268,7 +268,7 @@ def legacy
 end
 ```
 
-This will redirect the user to the main action if he tried to access a legacy action. The intention was to preserve the URL parameters to the legacy action and pass them to the main action. However, it can exploited by an attacker if he includes a host key in the URL:
+This will redirect the user to the main action if he tried to access a legacy action. The intention was to preserve the URL parameters to the legacy action and pass them to the main action. However, it can be exploited by an attacker if he includes a host key in the URL:
 
 ```
 http://www.example.com/site/legacy?param1=xy&param2=23&host=www.attacker.com
@@ -942,7 +942,7 @@ Or you can remove them.
 config.action_dispatch.default_headers.clear
 ```
 
-Here is the list of common headers:
+Here is a list of common headers:
 
 * X-Frame-Options
 _'SAMEORIGIN' in Rails by default_ - allow framing on same domain. Set it to 'DENY' to deny framing at all or 'ALLOWALL' if you want to allow framing for all website.
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 51d6775c3e..1d14656f79 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -118,7 +118,7 @@ Please read [Pull Request #9978](https://github.com/rails/rails/pull/9978) for d
 
 * Rails 4.0 changes the default memcached client from `memcache-client` to `dalli`. To upgrade, simply add `gem 'dalli'` to your `Gemfile`.
 
-* Rails 4.0 deprecates the `dom_id` and `dom_class` methods. You will need to include the `ActionView::RecordIdentifier` module in controllers requiring this feature.
+* Rails 4.0 deprecates the `dom_id` and `dom_class` methods in controllers (they are fine in views). You will need to include the `ActionView::RecordIdentifier` module in controllers requiring this feature.
 
 * Rails 4.0 changed how `assert_generates`, `assert_recognizes`, and `assert_routing` work. Now all these assertions raise `Assertion` instead of `ActionController::RoutingError`.