1 files changed, 49 insertions, 5 deletions
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index af3580a85b..88c9981dbb 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -104,13 +104,57 @@ Applications created before Rails 4.1 uses `Marshal` to serialize cookie values
 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
-  ```
+```ruby
+Rails.application.config.action_dispatch.cookies_serializer = :hybrid
+```
 
 This would transparently migrate your existing `Marshal`-serialized cookies into the
 new `JSON`-based format.
 
+When using the `:json` or `:hybrid` serializer, you should beware that not all
+Ruby objects can be serialized as JSON. For example, `Date` and `Time` objects
+will be serialized as strings, and `Hash`es will have their keys stringified.
+
+```ruby
+class CookiesController < ApplicationController
+  def set_cookie
+    cookies.encrypted[:expiration_date] = Date.tomorrow # => Thu, 20 Mar 2014
+    redirect_to action: 'read_cookie'
+  end
+
+  def read_cookie
+    cookies.encrypted[:expiration_date] # => "2014-03-20"
+  end
+end
+```
+
+It's advisable that you only store simple data (strings and numbers) in cookies.
+If you have to store complex objects, you would need to handle the conversion
+manually when reading the values on subsequent requests.
+
+If you use the cookie session store, this would apply to the `session` and
+`flash` hash as well.
+
+### Flash structure changes
+
+Flash message keys are
+[normalized to strings](https://github.com/rails/rails/commit/a668beffd64106a1e1fedb71cc25eaaa11baf0c1). They
+can still be accessed using either symbols or strings. Lopping through the flash
+will always yield string keys:
+
+```ruby
+flash["string"] = "a string"
+flash[:symbol] = "a symbol"
+
+# Rails < 4.1
+flash.keys # => ["string", :symbol]
+
+# Rails >= 4.1
+flash.keys # => ["string", "symbol"]
+```
+
+Make sure you are comparing Flash message keys against strings.
+
 ### Changes in JSON handling
 
 There are a few major changes related to JSON handling in Rails 4.1.
@@ -669,7 +713,7 @@ Upgrading from Rails 3.1 to Rails 3.2
 
 If your application is currently on any version of Rails older than 3.1.x, you should upgrade to Rails 3.1 before attempting an update to Rails 3.2.
 
-The following changes are meant for upgrading your application to Rails 3.2.16,
+The following changes are meant for upgrading your application to Rails 3.2.17,
 the last 3.2.x version of Rails.
 
 ### Gemfile
@@ -677,7 +721,7 @@ the last 3.2.x version of Rails.
 Make the following changes to your `Gemfile`.
 
 ```ruby
-gem 'rails', '3.2.16'
+gem 'rails', '3.2.17'
 
 group :assets do
   gem 'sass-rails',   '~> 3.2.6'