Merge pull request #13346 from chancancode/release_notes_etc

Release notes fixes [ci skip]

2 files changed, 145 insertions, 45 deletions

diff --git a/guides/source/4_1_release_notes.md b/guides/source/4_1_release_notes.md
index 1a76968139..ebeda1d25e 100644
--- a/guides/source/4_1_release_notes.md
+++ b/guides/source/4_1_release_notes.md
@@ -3,9 +3,10 @@ Ruby on Rails 4.1 Release Notes
 
 Highlights in Rails 4.1:
 
-* Variants
-* Spring
-* Action View extracted from Action Pack
+* Spring application preloader
+* `config/secrets.yml`
+* Action Pack variants
+* Action Mailer previews
 
 These release notes cover only the major changes. To know about various bug
 fixes and changes, please refer to the change logs or check out the
@@ -22,14 +23,84 @@ coverage before going in. You should also first upgrade to Rails 4.0 in case you
 haven't and make sure your application still runs as expected before attempting
 an update to Rails 4.1. A list of things to watch out for when upgrading is
 available in the
-[Upgrading to Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-4-0-to-rails-4-1)
+[Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-4-0-to-rails-4-1)
 guide.
 
 
 Major Features
 --------------
 
-### Variants
+### Spring application preloader
+
+Spring is a Rails application preloader. It speeds up development by keeping
+your application running in the background so you don't need to boot it every
+time you run a test, rake task or migration.
+
+New Rails 4.1 applications will ship with "springified" binstubs. This means
+that `bin/rails` and `bin/rake` will automatically take advantage of preloaded
+spring environments.
+
+**running rake tasks:**
+
+```
+bin/rake routes
+```
+
+**running tests:**
+
+```
+bin/rake test
+bin/rake test test/models
+bin/rake test test/models/user_test.rb
+```
+
+**running a console:**
+
+```
+bin/rails console
+```
+
+**spring introspection:**
+
+```
+$ bin/spring status
+Spring is running:
+
+ 1182 spring server | my_app | started 29 mins ago
+ 3656 spring app    | my_app | started 23 secs ago | test mode
+ 3746 spring app    | my_app | started 10 secs ago | development mode
+```
+
+Have a look at the
+[Spring README](https://github.com/jonleighton/spring/blob/master/README.md) to
+see all available features.
+
+See the [Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#spring)
+guide on how to migrate existing applications to use this feature.
+
+### `config/secrets.yml`
+
+Rails 4.1 will generate a new `secrets.yml` file in the `config` folder for new
+applications. By default, this file contains the application's `secret_key_base`,
+but it could also be used to store other secrets such as access keys for external
+APIs.
+
+The secrets added to this file will be accessible via `Rails.application.secrets`.
+For example, with the following `secrets.yml`:
+
+```yaml
+development:
+  secret_key_base: 3b7cd727ee24e8444053437c36cc66c3
+  some_api_key: SOMEKEY
+```
+
+`Rails.application.secrets.some_api_key` will return `SOMEKEY` in the development
+environment.
+
+See the [Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#config-secrets-yml)
+guide on how to migrate existing applications to use this feature.
+
+### Action Pack variants
 
 We often want to render different html/json/xml templates for phones,
 tablets, and desktop browsers. Variants makes it easy.
@@ -37,7 +108,7 @@ tablets, and desktop browsers. Variants makes it easy.
 The request variant is a specialization of the request format, like `:tablet`,
 `:phone`, or `:desktop`.
 
-You can set the variant in a before_action:
+You can set the variant in a `before_action`:
 
 ```ruby
 request.variant = :tablet if request.user_agent =~ /iPad/
@@ -72,46 +143,25 @@ respond_to do |format|
 end
 ```
 
-### Spring
-
-New Rails 4.1 applications will ship with "springified" binstubs. This means
-that `bin/rails` and `bin/rake` will automatically take advantage preloaded
-spring environments.
-
-**running rake tasks:**
-
-```
-bin/rake routes
-```
-
-**running tests:**
+### Action Mailer previews
 
-```
-bin/rake test
-bin/rake test test/models
-bin/rake test test/models/user_test.rb
-```
-
-**running a console:**
-
-```
-bin/rails console
-```
-
-**spring introspection:**
+Preview email templates in the browser without delivering them.
 
+```ruby
+class NotifierPreview < ActionMailer::Preview
+  # Accessible from http://localhost:3000/rails/mailers/notifier/welcome
+  def welcome
+    Notifier.welcome(User.first)
+  end
+end
 ```
-$ bin/spring status
-Spring is running:
 
- 1182 spring server | my_app | started 29 mins ago
- 3656 spring app    | my_app | started 23 secs ago | test mode
- 3746 spring app    | my_app | started 10 secs ago | development mode
-```
+By default, these preview files live in <tt>test/mailers/previews</tt>.
+This can be configured using the <tt>preview_path</tt> option.
 
-Have a look at the
-[Spring README](https://github.com/jonleighton/spring/blob/master/README.md) to
-see a all available features.
+See
+[action_mailer/base.rb](api.rubyonrails.org/v4.1.0/classes/ActionMailer/Base.html)
+for a detailed write up.
 
 ### Active Record enums
 
@@ -123,7 +173,7 @@ class Conversation < ActiveRecord::Base
   enum status: [ :active, :archived ]
 end
 
-conversation.archive!
+conversation.archived!
 conversation.active? # => false
 conversation.status  # => "archived"
 
@@ -134,7 +184,7 @@ See
 [active_record/enum.rb](api.rubyonrails.org/v4.1.0/classes/ActiveRecord/Enum.html)
 for a detailed write up.
 
-### Application message verifier.
+### Application message verifier
 
 Create a message verifier that can be used to generate and verify signed
 messages in the application.
@@ -145,9 +195,32 @@ Rails.application.message_verifier('salt').verify(message)
 # => 'my sensible data'
 ```
 
-Documentation
--------------
+### Module#concerning
+
+A natural, low-ceremony way to separate responsibilities within a class:
+
+```ruby
+class Todo < ActiveRecord::Base
+  concerning :EventTracking do
+    included do
+      has_many :events
+    end
+
+    def latest_event
+      ...
+    end
+
+    private
+      def some_internal_method
+        ...
+      end
+  end
+end
+```
 
+This example is equivalent to defining a `EventTracking` module inline,
+extending it with `ActiveSupport::Concern`, then mixing it in to the
+`Todo` class.
 
 Railties
 --------
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 1c233b4d82..b838874e2b 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -39,6 +39,33 @@ NOTE: User defined rake tasks will run in the `development` environment by
 default. If you want them to run in other environments consult the
 [Spring README](https://github.com/jonleighton/spring#rake).
 
+### `config/secrets.yml`
+
+If you want to use the new `secrets.yml` convention to store your application's
+secrets, you need to:
+
+1. Create a `secrets.yml` file in your `config` folder with the following content:
+
+    ```yaml
+    development:
+      secret_key_base:
+
+    test:
+      secret_key_base:
+
+    production:
+      secret_key_base:
+    ```
+
+2. Copy the existing `secret_key_base` from the `secret_token.rb` initializer to
+   `secrets.yml` under the `production` section.
+
+3. Remove the `secret_token.rb` initializer.
+
+4. Use `rake secret` to generate new keys for the `development` and `test` sections.
+
+5. Restart your server.
+
 ### Changes in JSON handling
 
 The are a few major changes related to JSON handling in Rails 4.1.