Updated CHANGELOG, docs, guides and release notes.

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

5 files changed, 44 insertions, 26 deletions

diff --git a/actionpack/CHANGELOG.md b/actionpack/CHANGELOG.md
index d3177df1c3..342f670e78 100644
--- a/actionpack/CHANGELOG.md
+++ b/actionpack/CHANGELOG.md
@@ -1,3 +1,17 @@
+*   Add new config option `config.action_dispatch.cookies_serializer` for
+    specifying a serializer for the signed and encrypted cookie jars.
+
+    The possible values are:
+
+    * `:json` - serialize cookie values with `JSON`
+    * `:marshal` - serialize cookie values with `Marshal`
+    * `:hybrid` - transparently migrate existing `Marshal` cookie values to `JSON`
+
+    For new apps `:json` option is added by default and `:marshal` is used
+    when no option is specified to maintain backwards compatibility.
+
+    *Łukasz Sarnacki*, *Matt Aimonetti*, *Guillermo Iguaran*, *Godfrey Chan*, *Rafael Mendonça França*
+
 *   `FlashHash` now behaves like a `HashWithIndifferentAccess`.
 
     *Guillermo Iguaran*
@@ -20,21 +34,6 @@
 
     *Josh Jordan*
 
-*   Add `:serializer` option for `config.session_store :cookie_store`. This
-    changes default serializer when using `:cookie_store`.
-
-    It is possible to pass:
-
-    * `:json` which is a secure wrapper on JSON using `JSON.parse` and
-      `JSON.generate` methods with quirks mode;
-    * `:marshal` which is a wrapper on Marshal;
-    * serializer class with `load` and `dump` methods defined.
-
-    For new apps `:json` option is added by default and :marshal is used
-    when no option is specified.
-
-    *Łukasz Sarnacki*, *Matt Aimonetti*
-
 *   Ensure that `request.filtered_parameters` is reset between calls to `process`
     in `ActionController::TestCase`.
 
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.
diff --git a/railties/lib/rails/generators/rails/app/templates/config/initializers/cookies_serializer.rb b/railties/lib/rails/generators/rails/app/templates/config/initializers/cookies_serializer.rb
new file mode 100644
index 0000000000..7a06a89f0f
--- /dev/null
+++ b/railties/lib/rails/generators/rails/app/templates/config/initializers/cookies_serializer.rb
@@ -0,0 +1,3 @@
+# Be sure to restart your server when you modify this file.
+
+Rails.application.config.action_dispatch.cookies_serializer = :json
\ No newline at end of file