16 files changed, 128 insertions, 62 deletions
diff --git a/guides/CHANGELOG.md b/guides/CHANGELOG.md
index 2730d2dfea..3a602efb3d 100644
--- a/guides/CHANGELOG.md
+++ b/guides/CHANGELOG.md
@@ -1,2 +1,6 @@
+## Rails 5.1.0.beta1 (February 23, 2017) ##
+
+*   No changes.
+
 
 Please check [5-0-stable](https://github.com/rails/rails/blob/5-0-stable/guides/CHANGELOG.md) for previous changes.
diff --git a/guides/Rakefile b/guides/Rakefile
index ccb42f3273..0a591558e1 100644
--- a/guides/Rakefile
+++ b/guides/Rakefile
@@ -2,15 +2,28 @@ namespace :guides do
   desc 'Generate guides (for authors), use ONLY=foo to process just "foo.md"'
   task generate: "generate:html"
 
+  # Guides are written in UTF-8, but the environment may be configured for some
+  # other locale, these tasks are responsible for ensuring the default external
+  # encoding is UTF-8.
+  #
+  # Real use cases: Generation was reported to fail on a machine configured with
+  # GBK (Chinese). The docs server once got misconfigured somehow and had "C",
+  # which broke generation too.
+  task :encoding do
+    %w(LANG LANGUAGE LC_ALL).each do |env_var|
+      ENV[env_var] = "en_US.UTF-8"
+    end
+  end
+
   namespace :generate do
     desc "Generate HTML guides"
-    task :html do
+    task :html => :encoding do
       ENV["WARNINGS"] = "1" # authors can't disable this
       ruby "rails_guides.rb"
     end
 
     desc "Generate .mobi file. The kindlegen executable must be in your PATH. You can get it for free from http://www.amazon.com/gp/feature.html?docId=1000765211"
-    task :kindle do
+    task :kindle => :encoding do
       require "kindlerb"
       unless Kindlerb.kindlegen_available?
         abort "Please run `setupkindlerb` to install kindlegen"
@@ -25,7 +38,7 @@ namespace :guides do
 
   # Validate guides -------------------------------------------------------------------------
   desc 'Validate guides, use ONLY=foo to process just "foo.html"'
-  task :validate do
+  task :validate => :encoding do
     ruby "w3c_validator.rb"
   end
 
diff --git a/guides/bug_report_templates/action_controller_master.rb b/guides/bug_report_templates/action_controller_master.rb
index 7644f6fe4a..486c7243ad 100644
--- a/guides/bug_report_templates/action_controller_master.rb
+++ b/guides/bug_report_templates/action_controller_master.rb
@@ -8,7 +8,6 @@ end
 gemfile(true) do
   source "https://rubygems.org"
   gem "rails", github: "rails/rails"
-  gem "arel", github: "rails/arel"
 end
 
 require "action_controller/railtie"
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 31220f9be2..31865ea375 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -1547,7 +1547,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
@@ -1871,7 +1871,7 @@ Which will execute:
 
 ```sql
 SELECT count(DISTINCT clients.id) AS count_all FROM clients
-  LEFT OUTER JOIN orders ON orders.client_id = client.id WHERE
+  LEFT OUTER JOIN orders ON orders.client_id = clients.id WHERE
   (clients.first_name = 'Ryan' AND orders.status = 'received')
 ```
 
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/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/i18n.md b/guides/source/i18n.md
index ed8cf8a344..6c8706bc13 100644
--- a/guides/source/i18n.md
+++ b/guides/source/i18n.md
@@ -707,6 +707,7 @@ The `:count` interpolation variable has a special role in that it both is interp
 
 ```ruby
 I18n.backend.store_translations :en, inbox: {
+  zero: 'no messages', # optional
   one: 'one message',
   other: '%{count} messages'
 }
@@ -715,15 +716,20 @@ I18n.translate :inbox, count: 2
 
 I18n.translate :inbox, count: 1
 # => 'one message'
+
+I18n.translate :inbox, count: 0
+# => 'no messages'
 ```
 
 The algorithm for pluralizations in `:en` is as simple as:
 
 ```ruby
-entry[count == 1 ? 0 : 1]
+lookup_key = :zero if count == 0 && entry.has_key?(:zero)
+lookup_key ||= count == 1 ? :one : :other
+entry[lookup_key]
 ```
 
-I.e. the translation denoted as `:one` is regarded as singular, the other is used as plural (including the count being zero).
+The translation denoted as `:one` is regarded as singular, and the `:other` is used as plural. If the count is zero, and a `:zero` entry is present, then it will be used instead of `:other`.
 
 If the lookup for the key does not return a Hash suitable for pluralization, an `I18n::InvalidPluralizationData` exception is raised.
 
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 652030a733..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.
@@ -1435,6 +1440,10 @@ variable. We then ensure that it was sent (the first assert), then, in the
 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
+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 8ba00a2b10..3afc0e5309 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -65,6 +65,25 @@ Overwrite /myapp/config/application.rb? (enter "h" for help) [Ynaqdh]
 
 Don't forget to review the difference, to see if there were any unexpected changes.
 
+Upgrading from Rails 5.0 to Rails 5.1
+-------------------------------------
+
+For more information on changes made to Rails 5.1 please see the [release notes](5_1_release_notes.html).
+
+### Top-level `HashWithIndifferentAccess` is soft-deprecated
+
+If your application uses the the top-level `HashWithIndifferentAccess` class, you
+should slowly move your code to use the `ActiveSupport::HashWithIndifferentAccess`
+one.
+
+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 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.
+
 Upgrading from Rails 4.2 to Rails 5.0
 -------------------------------------
 
diff --git a/guides/w3c_validator.rb b/guides/w3c_validator.rb
index c0a32c6b91..4671e040ca 100644
--- a/guides/w3c_validator.rb
+++ b/guides/w3c_validator.rb
@@ -32,7 +32,8 @@ include W3CValidators
 module RailsGuides
   class Validator
     def validate
-      validator = MarkupValidator.new
+      # https://github.com/w3c-validators/w3c_validators/issues/25
+      validator = NuValidator.new
       STDOUT.sync = true
       errors_on_guides = {}
 
@@ -44,11 +45,11 @@ module RailsGuides
           next
         end
 
-        if results.validity
-          print "."
-        else
+        if results.errors.length > 0
           print "E"
           errors_on_guides[f] = results.errors
+        else
+          print "."
         end
       end