Updated CHANGELOG, docs, guides and release notes.

Also added a `cookies_serializer.rb` initializer to the app template.

3 files changed, 27 insertions, 11 deletions

diff --git a/guides/source/4_1_release_notes.md b/guides/source/4_1_release_notes.md
index 90e6b2fcbc..8fcfc71351 100644
--- a/guides/source/4_1_release_notes.md
+++ b/guides/source/4_1_release_notes.md
@@ -346,10 +346,8 @@ for detailed changes.
   params "deep munging" that was used to address security vulnerability
   CVE-2013-0155. ([Pull Request](https://github.com/rails/rails/pull/13188))
 
-* Added `:serializer` option for `config.session_store :cookie_store`. This
-  changes default serializer when using
-  `:cookie_store`. ([Pull Request](https://github.com/rails/rails/pull/13692))
-
+* New config option `config.action_dispatch.cookies_serializer` for specifying
+  a serializer for the signed and encrypted cookie jars. (Pull Requests [1](https://github.com/rails/rails/pull/13692), [2](https://github.com/rails/rails/pull/13945) / [More Details](upgrading_ruby_on_rails.html#cookies-serializer))
 
 Action Mailer
 -------------
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index b142279991..222d86afe9 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -585,18 +585,23 @@ strings and deserializes them into Ruby objects on read.
 You can specify what serializer to use:
 
 ```ruby
-YourApp::Application.config.cookies_serializer :json
+Rails.application.config.action_dispatch.cookies_serializer = :json
 ```
 
-The possible options are `:marshal` or `:json`. The default serializer for new
-applications is `:json`. For compatibility with old applications with existing
-cookies, `:marshal` is used when `serializer` option is not specified.
+The default serializer for new applications is `:json`. For compatibility with
+old applications with existing cookies, `:marshal` is used when `serializer`
+option is not specified.
 
-It is also possible to pass a custom serializer class or object that responds
-to `load` and `dump`:
+You may also set this option to `:hybrid`, in which case Rails would transparently
+deserialize existing (`Marshal`-serialized) cookies on read and re-write them in
+the `JSON` format. This is useful for migrating existing applications to the
+`:json` serializer.
+
+It is also possible to pass a custom serializer that responds to `load` and
+`dump`:
 
 ```ruby
-YourApp::Application.config.cookies_serializer MyCustomSerializer
+Rails.application.config.action_dispatch.cookies_serializer = MyCustomSerializer
 ```
 
 Rendering XML and JSON data
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 2055452935..8aae3bbc1a 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -98,6 +98,19 @@ If your test helper contains a call to
 is now done automatically when you `require 'test_help'`, although
 leaving this line in your helper is not harmful in any way.
 
+### Cookies serializer
+
+Applications created before Rails 4.1 uses `Marshal` to serialize cookie values into
+the signed and encrypted cookie jars. If you want to use the new `JSON`-based format
+in your application, you can add an initializer file with the following content:
+
+  ```ruby
+  Rails.application.config.cookies_serializer :hybrid
+  ```
+
+This would transparently migrate your existing `Marshal`-serialized cookies into the
+new `JSON`-based format.
+
 ### Changes in JSON handling
 
 There are a few major changes related to JSON handling in Rails 4.1.