12 files changed, 74 insertions, 57 deletions
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 40eb838d32..69c4a00c5f 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -61,7 +61,7 @@ end
 
 The [Layouts & Rendering Guide](layouts_and_rendering.html) explains this in more detail.
 
-`ApplicationController` inherits from `ActionController::Base`, which defines a number of helpful methods. This guide will cover some of these, but if you're curious to see what's in there, you can see all of them in the API documentation or in the source itself.
+`ApplicationController` inherits from `ActionController::Base`, which defines a number of helpful methods. This guide will cover some of these, but if you're curious to see what's in there, you can see all of them in the [API documentation](http://api.rubyonrails.org/classes/ActionController.html) or in the source itself.
 
 Only public methods are callable as actions. It is a best practice to lower the visibility of methods (with `private` or `protected`) which are not intended to be actions, like auxiliary methods or filters.
 
diff --git a/guides/source/active_model_basics.md b/guides/source/active_model_basics.md
index 732e553c62..e26805d22c 100644
--- a/guides/source/active_model_basics.md
+++ b/guides/source/active_model_basics.md
@@ -87,7 +87,7 @@ end
 ### Conversion
 
 If a class defines `persisted?` and `id` methods, then you can include the
-`ActiveModel::Conversion` module in that class and call the Rails conversion
+`ActiveModel::Conversion` module in that class, and call the Rails conversion
 methods on objects of that class.
 
 ```ruby
@@ -156,16 +156,17 @@ person.changed? # => false
 person.first_name = "First Name"
 person.first_name # => "First Name"
 
-# returns true if any of the attributes have unsaved changes, false otherwise.
+# returns true if any of the attributes have unsaved changes.
 person.changed? # => true
 
 # returns a list of attributes that have changed before saving.
 person.changed # => ["first_name"]
 
-# returns a hash of the attributes that have changed with their original values.
+# returns a Hash of the attributes that have changed with their original values.
 person.changed_attributes # => {"first_name"=>nil}
 
-# returns a hash of changes, with the attribute names as the keys, and the values will be an array of the old and new value for that field.
+# returns a Hash of changes, with the attribute names as the keys, and the
+# values as an array of the old and new values for that field.
 person.changes # => {"first_name"=>[nil, "First Name"]}
 ```
 
@@ -179,7 +180,7 @@ person.first_name # => "First Name"
 person.first_name_changed? # => true
 ```
 
-Track what was the previous value of the attribute.
+Track the previous value of the attribute.
 
 ```ruby
 # attr_name_was accessor
@@ -187,7 +188,7 @@ person.first_name_was # => nil
 ```
 
 Track both previous and current value of the changed attribute. Returns an array
-if changed, else returns nil.
+if changed, otherwise returns nil.
 
 ```ruby
 # attr_name_change
@@ -197,7 +198,7 @@ person.last_name_change # => nil
 
 ### Validations
 
-The `ActiveModel::Validations` module adds the ability to validate class objects
+The `ActiveModel::Validations` module adds the ability to validate objects
 like in Active Record.
 
 ```ruby
@@ -225,7 +226,7 @@ person.valid?                        # => raises ActiveModel::StrictValidationFa
 
 ### Naming
 
-`ActiveModel::Naming` adds a number of class methods which make the naming and routing
+`ActiveModel::Naming` adds a number of class methods which make naming and routing
 easier to manage. The module defines the `model_name` class method which
 will define a number of accessors using some `ActiveSupport::Inflector` methods.
 
@@ -248,7 +249,7 @@ Person.model_name.singular_route_key  # => "person"
 
 ### Model
 
-`ActiveModel::Model` adds the ability to a class to work with Action Pack and
+`ActiveModel::Model` adds the ability for a class to work with Action Pack and
 Action View right out of the box.
 
 ```ruby
@@ -293,7 +294,7 @@ objects.
 ### Serialization
 
 `ActiveModel::Serialization` provides basic serialization for your object.
-You need to declare an attributes hash which contains the attributes you want to
+You need to declare an attributes Hash which contains the attributes you want to
 serialize. Attributes must be strings, not symbols.
 
 ```ruby
@@ -308,7 +309,7 @@ class Person
 end
 ```
 
-Now you can access a serialized hash of your object using the `serializable_hash`.
+Now you can access a serialized Hash of your object using the `serializable_hash` method.
 
 ```ruby
 person = Person.new
@@ -319,13 +320,14 @@ person.serializable_hash   # => {"name"=>"Bob"}
 
 #### ActiveModel::Serializers
 
-Rails provides an `ActiveModel::Serializers::JSON` serializer.
-This module automatically include the `ActiveModel::Serialization`.
+Active Model also provides the `ActiveModel::Serializers::JSON` module
+for JSON serializing / deserializing. This module automatically includes the
+previously discussed `ActiveModel::Serialization` module.
 
 ##### ActiveModel::Serializers::JSON
 
-To use the `ActiveModel::Serializers::JSON` you only need to change from
-`ActiveModel::Serialization` to `ActiveModel::Serializers::JSON`.
+To use `ActiveModel::Serializers::JSON` you only need to change the
+module you are including from `ActiveModel::Serialization` to `ActiveModel::Serializers::JSON`.
 
 ```ruby
 class Person
@@ -339,7 +341,8 @@ class Person
 end
 ```
 
-With the `as_json` method you have a hash representing the model.
+The `as_json` method, similar to `serializable_hash`, provides a Hash representing
+the model.
 
 ```ruby
 person = Person.new
@@ -348,8 +351,8 @@ person.name = "Bob"
 person.as_json # => {"name"=>"Bob"}
 ```
 
-From a JSON string you define the attributes of the model.
-You need to have the `attributes=` method defined on your class:
+You can also define the attributes for a model from a JSON string.
+However, you need to define the `attributes=` method on your class:
 
 ```ruby
 class Person
@@ -369,7 +372,7 @@ class Person
 end
 ```
 
-Now it is possible to create an instance of person and set the attributes using `from_json`.
+Now it is possible to create an instance of `Person` and set attributes using `from_json`.
 
 ```ruby
 json = { name: 'Bob' }.to_json
@@ -389,8 +392,8 @@ class Person
 end
 ```
 
-With the `human_attribute_name` you can transform attribute names into a more
-human format. The human format is defined in your locale file.
+With the `human_attribute_name` method, you can transform attribute names into a
+more human-readable format. The human-readable format is defined in your locale file(s).
 
 * config/locales/app.pt-BR.yml
 
@@ -411,7 +414,7 @@ Person.human_attribute_name('name') # => "Nome"
 `ActiveModel::Lint::Tests` allows you to test whether an object is compliant with
 the Active Model API.
 
-* app/models/person.rb
+* `app/models/person.rb`
 
     ```ruby
     class Person
@@ -419,7 +422,7 @@ the Active Model API.
     end
     ```
 
-* test/models/person_test.rb
+* `test/models/person_test.rb`
 
     ```ruby
     require 'test_helper'
@@ -454,9 +457,9 @@ features out of the box.
 ### SecurePassword
 
 `ActiveModel::SecurePassword` provides a way to securely store any
-password in an encrypted form. On including this module, a
+password in an encrypted form. When you include this module, a
 `has_secure_password` class method is provided which defines
-an accessor named `password` with certain validations on it.
+a `password` accessor with certain validations on it.
 
 #### Requirements
 
diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index 38a9d61f4b..2902c5d677 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -953,9 +953,6 @@ class Client < ApplicationRecord
 end
 ```
 
-NOTE: Please note that the optimistic locking will be ignored if you update the
-locking column's value.
-
 ### Pessimistic Locking
 
 Pessimistic locking uses a locking mechanism provided by the underlying database. Using `lock` when building a relation obtains an exclusive lock on the selected rows. Relations using `lock` are usually wrapped inside a transaction for preventing deadlock conditions.
@@ -1547,7 +1544,7 @@ SELECT people.id, people.name, comments.text
 FROM people
 INNER JOIN comments
   ON comments.person_id = people.id
-WHERE comments.created_at = '2015-01-01'
+WHERE comments.created_at > '2015-01-01'
 ```
 
 ### Retrieving specific data from multiple tables
diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md
index 32b38cde5e..5313361dfd 100644
--- a/guides/source/active_record_validations.md
+++ b/guides/source/active_record_validations.md
@@ -490,9 +490,6 @@ If you set `:only_integer` to `true`, then it will use the
 regular expression to validate the attribute's value. Otherwise, it will try to
 convert the value to a number using `Float`.
 
-WARNING. Note that the regular expression above allows a trailing newline
-character.
-
 ```ruby
 class Player < ApplicationRecord
   validates :points, numericality: true
diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md
index 68dde4482f..61b7112247 100644
--- a/guides/source/asset_pipeline.md
+++ b/guides/source/asset_pipeline.md
@@ -335,7 +335,7 @@ an asset has been updated and if so loads it into the page:
 <%= javascript_include_tag "application", "data-turbolinks-track" => "reload" %>
 ```
 
-In regular views you can access images in the `public/assets/images` directory
+In regular views you can access images in the `app/assets/images` directory
 like this:
 
 ```erb
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index 6e68935f9b..5794bfa666 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -154,7 +154,7 @@ case, the column definition might look like this:
 
 ```ruby
 create_table :accounts do |t|
-  t.belongs_to :supplier, index: true, unique: true, foreign_key: true
+  t.belongs_to :supplier, index: { unique: true }, foreign_key: true
   # ...
 end
 ```
@@ -582,14 +582,30 @@ class CreateBooks < ActiveRecord::Migration[5.0]
       t.string   :book_number
       t.integer  :author_id
     end
-
-    add_index :books, :author_id
   end
 end
 ```
 
 If you create an association some time after you build the underlying model, you need to remember to create an `add_column` migration to provide the necessary foreign key.
 
+It's a good practice to add an index on the foreign key to improve queries
+performance and a foreign key constraint to ensure referential data integrity:
+
+```ruby
+class CreateBooks < ActiveRecord::Migration[5.0]
+  def change
+    create_table :books do |t|
+      t.datetime :published_at
+      t.string   :book_number
+      t.integer  :author_id
+    end
+    
+    add_index :books, :author_id
+    add_foreign_key :books, :authors
+  end
+end
+```
+
 #### Creating Join Tables for `has_and_belongs_to_many` Associations
 
 If you create a `has_and_belongs_to_many` association, you need to explicitly create the joining table. Unless the name of the join table is explicitly specified by using the `:join_table` option, Active Record creates the name by using the lexical book of the class names. So a join between author and book models will give the default join table name of "authors_books" because "a" outranks "b" in lexical ordering.
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index de921e2705..a4f3882124 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -350,9 +350,9 @@ All these configuration options are delegated to the `I18n` library.
   `config/environments/production.rb` which is generated by Rails. The
   default value is `true` if this configuration is not set.
 
-* `config.active_record.dump_schemas` controls which database schemas will be dumped when calling db:structure:dump.
-  The options are `:schema_search_path` (the default) which dumps any schemas listed in schema_search_path,
-  `:all` which always dumps all schemas regardless of the schema_search_path,
+* `config.active_record.dump_schemas` controls which database schemas will be dumped when calling `db:structure:dump`.
+  The options are `:schema_search_path` (the default) which dumps any schemas listed in `schema_search_path`,
+  `:all` which always dumps all schemas regardless of the `schema_search_path`,
   or a string of comma separated schemas.
 
 * `config.active_record.belongs_to_required_by_default` is a boolean value and
@@ -362,10 +362,10 @@ All these configuration options are delegated to the `I18n` library.
 * `config.active_record.warn_on_records_fetched_greater_than` allows setting a
   warning threshold for query result size. If the number of records returned
   by a query exceeds the threshold, a warning is logged. This can be used to
-  identify queries which might be causing memory bloat.
+  identify queries which might be causing a memory bloat.
 
 * `config.active_record.index_nested_attribute_errors` allows errors for nested
-  has_many relationships to be displayed with an index as well as the error.
+  `has_many` relationships to be displayed with an index as well as the error.
   Defaults to `false`.
 
 * `config.active_record.use_schema_cache_dump` enables users to get schema cache information
diff --git a/guides/source/debugging_rails_applications.md b/guides/source/debugging_rails_applications.md
index ba0cdbf3af..33dee6a868 100644
--- a/guides/source/debugging_rails_applications.md
+++ b/guides/source/debugging_rails_applications.md
@@ -606,7 +606,6 @@ You can also inspect for an object method this way:
 @new_record = true
 @readonly = false
 @transaction_state = nil
-@txn = nil
 ```
 
 You can also use `display` to start watching variables. This is a good way of
diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md
index 8ad76ad01e..0508b0fb38 100644
--- a/guides/source/form_helpers.md
+++ b/guides/source/form_helpers.md
@@ -531,7 +531,7 @@ To leverage time zone support in Rails, you have to ask your users what time zon
 <%= time_zone_select(:person, :time_zone) %>
 ```
 
-There is also `time_zone_options_for_select` helper for a more manual (therefore more customizable) way of doing this. Read the API documentation to learn about the possible arguments for these two methods.
+There is also `time_zone_options_for_select` helper for a more manual (therefore more customizable) way of doing this. Read the [API documentation](http://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-time_zone_options_for_select) to learn about the possible arguments for these two methods.
 
 Rails _used_ to have a `country_select` helper for choosing countries, but this has been extracted to the [country_select plugin](https://github.com/stefanpenner/country_select). When using this, be aware that the exclusion or inclusion of certain names from the list can be somewhat controversial (and was the reason this functionality was extracted from Rails).
 
diff --git a/guides/source/security.md b/guides/source/security.md
index a81a782cf2..a57c6ea247 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -615,7 +615,7 @@ The two dashes start a comment ignoring everything after it. So the query return
 Usually a web application includes access control. The user enters their login credentials and the web application tries to find the matching record in the users table. The application grants access when it finds a record. However, an attacker may possibly bypass this check with SQL injection. The following shows a typical database query in Rails to find the first record in the users table which matches the login credentials parameters supplied by the user.
 
 ```ruby
-User.first("login = '#{params[:name]}' AND password = '#{params[:password]}'")
+User.find_by("login = '#{params[:name]}' AND password = '#{params[:password]}'")
 ```
 
 If an attacker enters ' OR '1'='1 as the name, and ' OR '2'>'1 as the password, the resulting SQL query will be:
@@ -762,7 +762,7 @@ s = sanitize(user_input, tags: tags, attributes: %w(href title))
 
 This allows only the given tags and does a good job, even against all kinds of tricks and malformed tags.
 
-As a second step, _it is good practice to escape all output of the application_, especially when re-displaying user input, which hasn't been input-filtered (as in the search form example earlier on). _Use `escapeHTML()` (or its alias `h()`) method_ to replace the HTML input characters &amp;, &quot;, &lt;, and &gt; by their uninterpreted representations in HTML (`&amp;`, `&quot;`, `&lt;`, and `&gt;`). 
+As a second step, _it is good practice to escape all output of the application_, especially when re-displaying user input, which hasn't been input-filtered (as in the search form example earlier on). _Use `escapeHTML()` (or its alias `h()`) method_ to replace the HTML input characters &amp;, &quot;, &lt;, and &gt; by their uninterpreted representations in HTML (`&amp;`, `&quot;`, `&lt;`, and `&gt;`).
 
 ##### Obfuscation and Encoding Injection
 
diff --git a/guides/source/testing.md b/guides/source/testing.md
index 4231500729..27f5b5e916 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -123,7 +123,7 @@ def test_the_truth
 end
 ```
 
-However only the `test` macro allows a more readable test name. You can still use regular method definitions though.
+Although you can still use regular method definitions, using the `test` macro allows for a more readable test name.
 
 NOTE: The method name is generated by replacing spaces with underscores. The result does not need to be a valid Ruby identifier though, the name may contain punctuation characters etc. That's because in Ruby technically any string may be a method name. This may require use of `define_method` and `send` calls to function properly, but formally there's little restriction on the name.
 
@@ -610,9 +610,9 @@ For creating Rails system tests, you use the `test/system` directory in your
 application. Rails provides a generator to create a system test skeleton for you.
 
 ```bash
-$ bin/rails generate system_test users_create_test
+$ bin/rails generate system_test users_create
       invoke test_unit
-      create test/system/users_create_test.rb
+      create test/system/users_creates_test.rb
 ```
 
 Here's what a freshly-generated system test looks like:
@@ -620,10 +620,12 @@ Here's what a freshly-generated system test looks like:
 ```ruby
 require "application_system_test_case"
 
-class UsersCreateTest < ApplicationSystemTestCase
-  visit users_url
-
-  assert_selector "h1", text: "Users"
+class UsersCreatesTest < ApplicationSystemTestCase
+  # test "visiting the index" do
+  #   visit users_creates_url
+  #
+  #   assert_selector "h1", text: "UsersCreate"
+  # end
 end
 ```
 
@@ -656,8 +658,8 @@ end
 
 The driver name is a required argument for `driven_by`. The optional arguments
 that can be passed to `driven_by` are `:using` for the browser (this will only
-be used for non-headless drivers like Selenium), `:on` for the port Puma should
-use, and `:screen_size` to change the size of the screen for screenshots.
+be used for non-headless drivers like Selenium), and `:screen_size` to change
+the size of the screen for screenshots.
 
 ```ruby
 require "test_helper"
@@ -728,6 +730,9 @@ Run the system tests.
 bin/rails test:system
 ```
 
+NOTE: By default, running `bin/rails test` won't run your system tests.
+Make sure to run `bin/rails test:system` to actually run them.
+
 #### Creating articles system test
 
 Now let's test the flow for creating a new article in our blog.
@@ -1436,7 +1441,7 @@ second batch of assertions, we ensure that the email does indeed contain what we
 expect. The helper `read_fixture` is used to read in the content from this file.
 
 NOTE: `email.body.to_s` is present when there's only one (HTML or text) part present.
-If the mailer provides both, you can test your fixture against specific parts 
+If the mailer provides both, you can test your fixture against specific parts
 with `email.text_part.body.to_s` or `email.html_part.body.to_s`.
 
 Here's the content of the `invite` fixture:
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 6005298127..3afc0e5309 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -80,7 +80,7 @@ It is only soft-deprecated, which means that your code will not break at the
 moment and no deprecation warning will be displayed but this constant will be
 removed in the future.
 
-Also, if you have pretty old YAML documents containg dumps of such objects,
+Also, if you have pretty old YAML documents containing dumps of such objects,
 you may need to load and dump them again to make sure that they reference
 the right constant and that loading them won't break in the future.