7 files changed, 122 insertions, 25 deletions
diff --git a/guides/CHANGELOG.md b/guides/CHANGELOG.md
index cd3fa9f65b..99d69d5eda 100644
--- a/guides/CHANGELOG.md
+++ b/guides/CHANGELOG.md
@@ -1,3 +1,7 @@
+*   New section in Active Record Association Basics: Single Table Inheritance
+
+    *Andrey Nering*
+
 *   New section in Active Record Querying: Understanding The Method Chaining
 
     *Andrey Nering*
diff --git a/guides/source/active_record_migrations.md b/guides/source/active_record_migrations.md
index 97cabc1728..b8db21a989 100644
--- a/guides/source/active_record_migrations.md
+++ b/guides/source/active_record_migrations.md
@@ -479,7 +479,8 @@ Rails will generate a name for every foreign key starting with
 There is a `:name` option to specify a different name if needed.
 
 NOTE: Active Record only supports single column foreign keys. `execute` and
-`structure.sql` are required to use composite foreign keys.
+`structure.sql` are required to use composite foreign keys. See
+[Schema Dumping and You](#schema-dumping-and-you).
 
 Removing a foreign key is easy as well:
 
@@ -695,6 +696,10 @@ of `create_table` and `reversible`, replacing `create_table`
 by `drop_table`, and finally replacing `up` by `down` and vice-versa.
 This is all taken care of by `revert`.
 
+NOTE: If you want to add check constraints like in the examples above,
+you will have to use `structure.sql` as dump method. See
+[Schema Dumping and You](#schema-dumping-and-you).
+
 Running Migrations
 ------------------
 
@@ -943,10 +948,10 @@ that Active Record supports. This could be very useful if you were to
 distribute an application that is able to run against multiple databases.
 
 There is however a trade-off: `db/schema.rb` cannot express database specific
-items such as triggers, or stored procedures. While in a migration you can
-execute custom SQL statements, the schema dumper cannot reconstitute those
-statements from the database. If you are using features like this, then you
-should set the schema format to `:sql`.
+items such as triggers, stored procedures or check constraints. While in a
+migration you can execute custom SQL statements, the schema dumper cannot
+reconstitute those statements from the database. If you are using features like
+this, then you should set the schema format to `:sql`.
 
 Instead of using Active Record's schema dumper, the database's structure will
 be dumped using a tool specific to the database (via the `db:structure:dump`
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index dab885a8fb..8633cc4f10 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -2243,3 +2243,67 @@ Extensions can refer to the internals of the association proxy using these three
 * `proxy_association.owner` returns the object that the association is a part of.
 * `proxy_association.reflection` returns the reflection object that describes the association.
 * `proxy_association.target` returns the associated object for `belongs_to` or `has_one`, or the collection of associated objects for `has_many` or `has_and_belongs_to_many`.
+
+Single Table Inheritance
+------------------------
+
+Sometimes, you may want to share fields and behavior between different models.
+Let's say we have Car, Motorcycle and Bicycle models. We will want to share
+the `color` and `price` fields and some methods for all of them, but having some
+specific behavior for each, and separated controllers too.
+
+Rails makes this quite easy. First, let's generate the base Vehicle model:
+
+```bash
+$ rails generate model vehicle type:string color:string price:decimal{10.2}
+```
+
+Did you note we are adding a "type" field? Since all models will be saved in a
+single database table, Rails will save in this column the name of the model that
+is being saved. In our example, this can be "Car", "Motorcycle" or "Bicycle."
+STI won't work without a "type" field in the table.
+
+Next, we will generate the three models that inherit from Vehicle. For this,
+we can use the `--parent=PARENT` option, which will generate a model that
+inherits from the specified parent and without equivalent migration (since the
+table already exists).
+
+For example, to generate the Car model:
+
+```bash
+$ rails generate model car --parent=Vehicle
+```
+
+The generated model will look like this:
+
+```ruby
+class Car < Vehicle
+end
+```
+
+This means that all behavior added to Vehicle is available for Car too, as
+associations, public methods, etc.
+
+Creating a car will save it in the `vehicles` table with "Car" as the `type` field:
+
+```ruby
+Car.create color: 'Red', price: 10000
+```
+
+will generate the following SQL:
+
+```sql
+INSERT INTO "vehicles" ("type", "color", "price") VALUES ("Car", "Red", 10000)
+```
+
+Querying car records will just search for vehicles that are cars:
+
+```ruby
+Car.all
+```
+
+will run a query like:
+
+```sql
+SELECT "vehicles".* FROM "vehicles" WHERE "vehicles"."type" IN ('Car')
+```
diff --git a/guides/source/autoloading_and_reloading_constants.md b/guides/source/autoloading_and_reloading_constants.md
index 51c46d707c..f0ef03f0ce 100644
--- a/guides/source/autoloading_and_reloading_constants.md
+++ b/guides/source/autoloading_and_reloading_constants.md
@@ -324,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:
 
diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md
index 7381521658..e06706d750 100644
--- a/guides/source/contributing_to_ruby_on_rails.md
+++ b/guides/source/contributing_to_ruby_on_rails.md
@@ -173,6 +173,14 @@ $ git checkout -b my_new_branch
 
 It doesn't matter much what name you use, because this branch will only exist on your local computer and your personal repository on GitHub. It won't be part of the Rails Git repository.
 
+### Bundle Update
+
+Update and install the required gems.
+
+```bash
+$ bundle update
+```
+
 ### Running an Application Against Your Local Branch
 
 In case you need a dummy Rails app to test changes, the `--dev` flag of `rails new` generates an application that uses your local branch:
diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md
index 4c02c99cc7..90004c611b 100644
--- a/guides/source/form_helpers.md
+++ b/guides/source/form_helpers.md
@@ -687,7 +687,14 @@ class LabellingFormBuilder < ActionView::Helpers::FormBuilder
 end
 ```
 
-If you reuse this frequently you could define a `labeled_form_for` helper that automatically applies the `builder: LabellingFormBuilder` option.
+If you reuse this frequently you could define a `labeled_form_for` helper that automatically applies the `builder: LabellingFormBuilder` option:
+
+```ruby
+def labeled_form_for(record, options = {}, &block)
+  options.merge! builder: LabellingFormBuilder
+  form_for record, options, &block
+end
+```
 
 The form builder used also determines what happens when you do
 
diff --git a/guides/source/testing.md b/guides/source/testing.md
index fa55c09c64..a083b3f981 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -480,21 +480,28 @@ In the `test_should_get_index` test, Rails simulates a request on the action cal
 
 The `get` method kicks off the web request and populates the results into the response. It accepts 4 arguments:
 
-* The action of the controller you are requesting. This can be in the form of a string or a symbol.
-* An optional hash of request parameters to pass into the action (eg. query string parameters or article variables).
-* An optional hash of session variables to pass along with the request.
-* An optional hash of flash values.
+* The action of the controller you are requesting.
+  This can be in the form of a string or a symbol.
+
+* `params`: option with a hash of request parameters to pass into the action
+  (e.g. query string parameters or article variables).
+
+* `session`: option with a hash of session variables to pass along with the request.
+
+* `flash`: option with a hash of flash values.
+
+All the keyword arguments are optional.
 
 Example: Calling the `:show` action, passing an `id` of 12 as the `params` and setting a `user_id` of 5 in the session:
 
 ```ruby
-get(:show, {'id' => "12"}, {'user_id' => 5})
+get(:show, params: { 'id' => "12" }, session: { 'user_id' => 5 })
 ```
 
 Another example: Calling the `:view` action, passing an `id` of 12 as the `params`, this time with no session, but with a flash message.
 
 ```ruby
-get(:view, {'id' => '12'}, nil, {'message' => 'booya!'})
+get(:view, params: { 'id' => '12' }, flash: { 'message' => 'booya!' })
 ```
 
 NOTE: If you try running `test_should_create_article` test from `articles_controller_test.rb` it will fail on account of the newly added model level validation and rightly so.
@@ -504,7 +511,7 @@ Let us modify `test_should_create_article` test in `articles_controller_test.rb`
 ```ruby
 test "should create article" do
   assert_difference('Article.count') do
-    post :create, article: {title: 'Some title'}
+    post :create, params: { article: { title: 'Some title' } }
   end
 
   assert_redirected_to article_path(assigns(:article))
@@ -534,7 +541,7 @@ NOTE: Functional tests do not verify whether the specified request type is accep
 
 ```ruby
 test "ajax request responds with no layout" do
-  xhr :get, :show, id: articles(:first).id
+  xhr :get, :show, params: { id: articles(:first).id }
 
   assert_template :index
   assert_template layout: nil
@@ -638,7 +645,7 @@ Let's start by adding this assertion to our `test_should_create_article` test:
 ```ruby
 test "should create article" do
   assert_difference('Article.count') do
-    post :create, article: {title: 'Some title'}
+    post :create, params: { article: { title: 'Some title' } }
   end
 
   assert_redirected_to article_path(assigns(:article))
@@ -708,7 +715,7 @@ Let's write a test for the `:show` action:
 ```ruby
 test "should show article" do
   article = articles(:one)
-  get :show, id: article.id
+  get :show, params: { id: article.id }
   assert_response :success
 end
 ```
@@ -721,7 +728,7 @@ How about deleting an existing Article?
 test "should destroy article" do
   article = articles(:one)
   assert_difference('Article.count', -1) do
-    delete :destroy, id: article.id
+    delete :destroy, params: { id: article.id }
   end
 
   assert_redirected_to articles_path
@@ -733,7 +740,7 @@ We can also add a test for updating an existing Article.
 ```ruby
 test "should update article" do
   article = articles(:one)
-  patch :update, id: article.id, article: {title: "updated"}
+  patch :update, params: { id: article.id, article: { title: "updated" } }
   assert_redirected_to article_path(assigns(:article))
 end
 ```
@@ -759,20 +766,20 @@ class ArticlesControllerTest < ActionController::TestCase
 
   test "should show article" do
     # Reuse the @article instance variable from setup
-    get :show, id: @article.id
+    get :show, params: { id: @article.id }
     assert_response :success
   end
 
   test "should destroy article" do
     assert_difference('Article.count', -1) do
-      delete :destroy, id: @article.id
+      delete :destroy, params: { id: @article.id }
     end
 
     assert_redirected_to articles_path
   end
 
   test "should update article" do
-    patch :update, id: @article.id, article: {title: "updated"}
+    patch :update, params: { id: @article.id, article: { title: "updated" } }
     assert_redirected_to article_path(assigns(:article))
   end
 end
@@ -1026,7 +1033,8 @@ test "can create an article" do
   assert_response :success
   assert_template "articles/new", partial: "articles/_form"
 
-  post "/articles", article: {title: "can create", body: "article successfully."}
+  post "/articles",
+    params: { article: { title: "can create", body: "article successfully." } }
   assert_response :redirect
   follow_redirect!
   assert_response :success
@@ -1042,7 +1050,8 @@ We start by calling the `:new` action on our Articles controller. This response
 After this we make a post request to the `:create` action of our Articles controller:
 
 ```ruby
-post "/articles", article: {title: "can create", body: "article successfully."}
+post "/articles",
+  params: { article: { title: "can create", body: "article successfully." } }
 assert_response :redirect
 follow_redirect!
 ```
@@ -1147,7 +1156,7 @@ require 'test_helper'
 class UserControllerTest < ActionController::TestCase
   test "invite friend" do
     assert_difference 'ActionMailer::Base.deliveries.size', +1 do
-      post :invite_friend, email: 'friend@example.com'
+      post :invite_friend, params: { email: 'friend@example.com' }
     end
     invite_email = ActionMailer::Base.deliveries.last