12 files changed, 335 insertions, 48 deletions
diff --git a/guides/source/5_1_release_notes.md b/guides/source/5_1_release_notes.md
new file mode 100644
index 0000000000..5d4885d55c
--- /dev/null
+++ b/guides/source/5_1_release_notes.md
@@ -0,0 +1,277 @@
+**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON http://guides.rubyonrails.org.**
+
+Ruby on Rails 5.1 Release Notes
+===============================
+
+Highlights in Rails 5.1:
+
+* Yarn Support
+* Optional Webpack support
+* jQuery no longer a default dependency
+* System tests
+* Encrypted secrets
+* Parameterized mailers
+* Direct & resolved routes
+* Unification of form_for and form_tag into form_with
+
+These release notes cover only the major changes. To learn about various bug
+fixes and changes, please refer to the change logs or check out the [list of
+commits](https://github.com/rails/rails/commits/5-1-stable) in the main Rails
+repository on GitHub.
+
+--------------------------------------------------------------------------------
+
+Upgrading to Rails 5.1
+----------------------
+
+ToDo
+
+Major Features
+--------------
+
+### Yarn Support
+
+[Pull Request](https://github.com/rails/rails/pull/26836)
+
+Rails 5.1 will allow managing JavaScript dependencies
+from NPM via Yarn. This will make it easy to use libraries like React, VueJS
+or any other library from NPM world. The Yarn support is integrated with
+the asset pipeline so that all dependencies will work seamlessly with the
+Rails 5.1 app.
+
+### Optional Webpack support
+
+[Pull Request](https://github.com/rails/rails/pull/27288)
+
+Rails apps can integrate with [Webpack](https://webpack.js.org/), a JavaScript
+asset bundler, more easily using the new [Webpacker](https://github.com/rails/webpacker)
+gem. Use the `--webpack` flag when generating new applications to enable Webpack
+integration.
+
+This is fully compatible with the asset pipeline, which you can continue to use for
+images, fonts, sounds, and other assets. You can even have some JavaScript code
+managed by the asset pipeline, and other code processed via Webpack. All of this is managed
+by Yarn, which is enabled by default.
+
+### jQuery no longer a default dependency
+
+[Pull Request](https://github.com/rails/rails/pull/27113)
+
+jQuery was required by default in earlier versions of Rails to provide features
+like `data-remote`, `data-confirm` and other parts of Rails' Unobtrusive JavaScript
+offerings. It is no longer required, as the UJS has been rewritten to use plain,
+vanilla JavaScript. This code now ships inside of Action View as
+`rails-ujs`.
+
+You can still use the jQuery version if needed, but it is no longer required by default.
+
+### System tests
+
+[Pull Request](https://github.com/rails/rails/pull/26703)
+
+Rails 5.1 has baked-in support for writing Capybara tests, in the form of
+System tests. You need no longer worry about configuring Capybara and
+database cleaning strategies for such tests. Rails 5.1 provides a wrapper
+for running tests in Chrome with additional features such as failure
+screenshots.
+
+### Encrypted secrets
+
+[Pull Request](https://github.com/rails/rails/pull/28038)
+
+Rails will now allow management of application secrets in a secure way,
+building on top of the [sekrets](https://github.com/ahoward/sekrets) gem.
+
+Run `bin/rails secrets:setup` to setup a new encrypted secrets file. This will
+also generate a master key, which must be stored outside of the repository. The
+secrets themselves can then be safely checked into the revision control system,
+in an encrypted form.
+
+Secrets will be decrypted in production, using a key stored either in the
+`RAILS_MASTER_KEY` environment variable, or in a key file.
+
+### Parameterized mailers
+
+[Pull Request](https://github.com/rails/rails/pull/27825)
+
+Allows specifying common params used for all methods in a mailer class
+to share instance variables, headers and other common setup.
+
+``` ruby
+class InvitationsMailer < ApplicationMailer
+
+  before_action { @inviter, @invitee = params[:inviter], params[:invitee] }
+  before_action { @account = params[:inviter].account }
+
+  def account_invitation
+    mail subject: "#{@inviter.name} invited you to their Basecamp (#{@account.name})"
+  end
+
+  def project_invitation
+    @project    = params[:project]
+    @summarizer = ProjectInvitationSummarizer.new(@project.bucket)
+
+    mail subject: "#{@inviter.name.familiar} added you to a project in Basecamp (#{@account.name})"
+  end
+end
+
+InvitationsMailer.with(inviter: person_a, invitee: person_b).account_invitation.deliver_later
+```
+
+### Direct & resolved routes
+
+[Pull Request](https://github.com/rails/rails/pull/23138)
+
+Rails 5.1 has added two new methods, `resolve` and `direct`, to the routing
+DSL.
+
+The `resolve` method allows customizing polymorphic mapping of models.
+
+``` ruby
+resource :basket
+
+resolve("Basket") { [:basket] }
+```
+
+``` erb
+<%= form_for @basket do |form| %>
+  <!-- basket form -->
+<% end %>
+```
+
+This will generate the singular URL `/basket` instead of the usual `/baskets/:id`.
+
+The `direct` method allows creation of custom URL helpers.
+
+``` ruby
+direct(:homepage) { "http://www.rubyonrails.org" }
+
+>> homepage_url
+=> "http://www.rubyonrails.org"
+```
+
+The return value of the block must be a valid argument for the `url_for`
+method. So, you can pass a valid string URL, Hash, Array, an
+Active Model instance, or an Active Model class.
+
+``` ruby
+direct :commentable do |model|
+  [ model, anchor: model.dom_id ]
+end
+
+direct :main do
+  { controller: 'pages', action: 'index', subdomain: 'www' }
+end
+```
+
+### Unification of form_for and form_tag into form_with
+
+[Pull Request](https://github.com/rails/rails/pull/26976)
+
+Before Rails 5.1, there were two interfaces for handling HTML forms:
+`form_for` for model instances and `form_tag` for custom URLs.
+
+Rails 5.1 combines both of these interfaces with `form_with`, and
+can generate form tags based on URLs, scopes or models.
+
+``` erb
+# Using just a URL:
+
+<%= form_with url: posts_path do |form| %>
+  <%= form.text_field :title %>
+<% end %>
+
+# =>
+<form action="/posts" method="post" data-remote="true">
+  <input type="text" name="title">
+</form>
+
+# Adding a scope prefixes the input field names:
+
+<%= form_with scope: :post, url: posts_path do |form| %>
+  <%= form.text_field :title %>
+<% end %>
+# =>
+<form action="/posts" method="post" data-remote="true">
+  <input type="text" name="post[title]">
+</form>
+
+# Using a model infers both the URL and scope:
+
+<%= form_with model: Post.new do |form| %>
+  <%= form.text_field :title %>
+<% end %>
+# =>
+<form action="/posts" method="post" data-remote="true">
+  <input type="text" name="post[title]">
+</form>
+
+# An existing model makes an update form and fills out field values:
+
+<%= form_with model: Post.first do |form| %>
+  <%= form.text_field :title %>
+<% end %>
+# =>
+<form action="/posts/1" method="post" data-remote="true">
+  <input type="hidden" name="_method" value="patch">
+  <input type="text" name="post[title]" value="<the title of the post>">
+</form>
+```
+
+Railties
+--------
+
+Please refer to the [Changelog][railties] for detailed changes.
+
+Action Pack
+-----------
+
+Please refer to the [Changelog][action-pack] for detailed changes.
+
+Action View
+-------------
+
+Please refer to the [Changelog][action-view] for detailed changes.
+
+Action Mailer
+-------------
+
+Please refer to the [Changelog][action-mailer] for detailed changes.
+
+Active Record
+-------------
+
+Please refer to the [Changelog][active-record] for detailed changes.
+
+Active Model
+------------
+
+Please refer to the [Changelog][active-model] for detailed changes.
+
+Active Job
+-----------
+
+Please refer to the [Changelog][active-job] for detailed changes.
+
+Active Support
+--------------
+
+Please refer to the [Changelog][active-support] for detailed changes.
+
+Credits
+-------
+
+See the
+[full list of contributors to Rails](http://contributors.rubyonrails.org/) for
+the many people who spent many hours making Rails, the stable and robust
+framework it is. Kudos to all of them.
+
+[railties]:       https://github.com/rails/rails/blob/5-1-stable/railties/CHANGELOG.md
+[action-pack]:    https://github.com/rails/rails/blob/5-1-stable/actionpack/CHANGELOG.md
+[action-view]:    https://github.com/rails/rails/blob/5-1-stable/actionview/CHANGELOG.md
+[action-mailer]:  https://github.com/rails/rails/blob/5-1-stable/actionmailer/CHANGELOG.md
+[action-cable]:   https://github.com/rails/rails/blob/5-1-stable/actioncable/CHANGELOG.md
+[active-record]:  https://github.com/rails/rails/blob/5-1-stable/activerecord/CHANGELOG.md
+[active-model]:   https://github.com/rails/rails/blob/5-1-stable/activemodel/CHANGELOG.md
+[active-support]: https://github.com/rails/rails/blob/5-1-stable/activesupport/CHANGELOG.md
+[active-job]:     https://github.com/rails/rails/blob/5-1-stable/activejob/CHANGELOG.md
diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md
index 380fdac658..9673571909 100644
--- a/guides/source/action_mailer_basics.md
+++ b/guides/source/action_mailer_basics.md
@@ -550,8 +550,9 @@ url helper.
 <%= user_url(@user, host: 'example.com') %>
 ```
 
-NOTE: non-`GET` links require [jQuery UJS](https://github.com/rails/jquery-ujs)
-and won't work in mailer templates. They will result in normal `GET` requests.
+NOTE: non-`GET` links require [rails-ujs](https://github.com/rails/rails-ujs) or
+[jQuery UJS](https://github.com/rails/jquery-ujs), and won't work in mailer templates.
+They will result in normal `GET` requests.
 
 ### Adding images in Action Mailer Views
 
diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md
index c65d1e6de5..b58ca61848 100644
--- a/guides/source/active_job_basics.md
+++ b/guides/source/active_job_basics.md
@@ -114,7 +114,7 @@ For enqueuing and executing jobs in production you need to set up a queuing back
 that is to say you need to decide for a 3rd-party queuing library that Rails should use.
 Rails itself only provides an in-process queuing system, which only keeps the jobs in RAM.
 If the process crashes or the machine is reset, then all outstanding jobs are lost with the
-default async back-end. This may be fine for smaller apps or non-critical jobs, but most
+default async backend. This may be fine for smaller apps or non-critical jobs, but most
 production apps will need to pick a persistent backend.
 
 ### Backends
diff --git a/guides/source/active_model_basics.md b/guides/source/active_model_basics.md
index 72daa29f7f..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 includes 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 31865ea375..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.
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/caching_with_rails.md b/guides/source/caching_with_rails.md
index fd7626250c..aa79f59e4f 100644
--- a/guides/source/caching_with_rails.md
+++ b/guides/source/caching_with_rails.md
@@ -396,7 +396,7 @@ config.cache_store = :file_store, "/path/to/cache/directory"
 ```
 
 With this cache store, multiple server processes on the same host can share a
-cache. The cache store is appropriate for low to medium traffic sites that are
+cache. This cache store is appropriate for low to medium traffic sites that are
 served off one or two hosts. Server processes running on different hosts could
 share a cache by using a shared file system, but that setup is not recommended.
 
@@ -570,6 +570,20 @@ You can also set the strong ETag directly on the response.
   response.strong_etag = response.body # => "618bbc92e2d35ea1945008b42799b0e7"
 ```
 
+Caching in Development
+----------------------
+
+It's common to want to test the caching strategy of your application
+in development mode. Rails provides the rake task `dev:cache` to 
+easily toggle caching on/off.
+
+```bash
+$ bin/rails dev:cache
+Development mode is now being cached.
+$ bin/rails dev:cache
+Development mode is no longer being cached.
+```
+
 References
 ----------
 
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/maintenance_policy.md b/guides/source/maintenance_policy.md
index 7ced3eab1c..1d6a4edb5b 100644
--- a/guides/source/maintenance_policy.md
+++ b/guides/source/maintenance_policy.md
@@ -44,7 +44,7 @@ from.
 In special situations, where someone from the Core Team agrees to support more series,
 they are included in the list of supported series.
 
-**Currently included series:** `5.0.Z`, `4.2.Z`.
+**Currently included series:** `5.1.Z`.
 
 Security Issues
 ---------------
@@ -59,7 +59,7 @@ be built from 1.2.2, and then added to the end of 1-2-stable. This means that
 security releases are easy to upgrade to if you're running the latest version
 of Rails.
 
-**Currently included series:** `5.0.Z`, `4.2.Z`.
+**Currently included series:** `5.1.Z`, `5.0.Z`.
 
 Severe Security Issues
 ----------------------
@@ -68,7 +68,7 @@ For severe security issues we will provide new versions as above, and also the
 last major release series will receive patches and new versions. The
 classification of the security issue is judged by the core team.
 
-**Currently included series:** `5.0.Z`, `4.2.Z`.
+**Currently included series:** `5.1.Z`, `5.0.Z`, `4.2.Z`.
 
 Unsupported Release Series
 --------------------------
diff --git a/guides/source/security.md b/guides/source/security.md
index a57c6ea247..a14134f8c1 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -257,13 +257,12 @@ protect_from_forgery with: :exception
 
 This will automatically include a security token in all forms and Ajax requests generated by Rails. If the security token doesn't match what was expected, an exception will be thrown.
 
-NOTE: By default, Rails includes jQuery and an [unobtrusive scripting adapter for
-jQuery](https://github.com/rails/jquery-ujs), which adds a header called
-`X-CSRF-Token` on every non-GET Ajax call made by jQuery with the security token.
-Without this header, non-GET Ajax requests won't be accepted by Rails. When using
-another library to make Ajax calls, it is necessary to add the security token as
-a default header for Ajax calls in your library. To get the token, have a look at
-`<meta name='csrf-token' content='THE-TOKEN'>` tag printed by
+NOTE: By default, Rails includes an [unobtrusive scripting adapter](https://github.com/rails/rails-ujs),
+which adds a header called `X-CSRF-Token` with the security token on every non-GET
+Ajax call. Without this header, non-GET Ajax requests won't be accepted by Rails.
+When using another library to make Ajax calls, it is necessary to add the security
+token as a default header for Ajax calls in your library. To get the token, have
+a look at `<meta name='csrf-token' content='THE-TOKEN'>` tag printed by
 `<%= csrf_meta_tags %>` in your application view.
 
 It is common to use persistent cookies to store user information, with `cookies.permanent` for example. In this case, the cookies will not be cleared and the out of the box CSRF protection will not be effective. If you are using a different cookie store than the session for this information, you must handle what to do with it yourself:
diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md
index c1dfcab6f3..e04b3e3581 100644
--- a/guides/source/working_with_javascript_in_rails.md
+++ b/guides/source/working_with_javascript_in_rails.md
@@ -149,7 +149,7 @@ Because of Unobtrusive JavaScript, the Rails "Ajax helpers" are actually in two
 parts: the JavaScript half and the Ruby half.
 
 Unless you have disabled the Asset Pipeline,
-[rails.js](https://github.com/rails/jquery-ujs/blob/master/src/rails.js)
+[rails-ujs](https://github.com/rails/rails-ujs/blob/master/src/rails-ujs.coffee)
 provides the JavaScript half, and the regular Ruby view helpers add appropriate
 tags to your DOM.