Document the change in `nil` handling for serialized attributes

Also updated the test case to reflect that

2 files changed, 17 insertions, 9 deletions

diff --git a/activerecord/test/cases/serialized_attribute_test.rb b/activerecord/test/cases/serialized_attribute_test.rb
index d7e6d3465f..f8d87a3661 100644
--- a/activerecord/test/cases/serialized_attribute_test.rb
+++ b/activerecord/test/cases/serialized_attribute_test.rb
@@ -81,22 +81,25 @@ class SerializedAttributeTest < ActiveRecord::TestCase
     assert_equal(my_post.title, t.content["title"])
   end
 
-  # This is to ensure that the JSON coder is behaving the same way as 4.0, but
-  # we can consider changing this in the future.
-  def test_json_db_null
+  def test_json_read_legacy_null
     Topic.serialize :content, JSON
 
-    # Force a row to have a database NULL instead of a JSON "null"
-    id = Topic.connection.insert "INSERT INTO topics (content) VALUES(NULL)"
+    # Force a row to have a JSON "null" instead of a database NULL (this is how
+    # null values are saved on 4.1 and before)
+    id = Topic.connection.insert "INSERT INTO topics (content) VALUES('null')"
     t = Topic.find(id)
 
     assert_nil t.content
+  end
 
-    t.save!
+  def test_json_read_db_null
+    Topic.serialize :content, JSON
 
-    # On 4.0, re-saving a row with a database NULL will turn that into a JSON
-    # "null"
-    assert_equal 1, Topic.where("content = 'null'").count
+    # Force a row to have a database NULL instead of a JSON "null"
+    id = Topic.connection.insert "INSERT INTO topics (content) VALUES(NULL)"
+    t = Topic.find(id)
+
+    assert_nil t.content
   end
 
   def test_serialized_attribute_declared_in_subclass
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 36cd505977..b3e4505fc0 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -52,6 +52,11 @@ Upgrading from Rails 4.1 to Rails 4.2
 
 NOTE: This section is a work in progress.
 
+### Serialized attributes
+
+When assigning `nil` to a serialized attribute, it will be saved to the database
+as `NULL` instead of passing the `nil` value through the coder (e.g. `"null"`
+when using the `JSON` coder).
 
 Upgrading from Rails 4.0 to Rails 4.1
 -------------------------------------