Update documentation on STI change handling

Documenting a potential source of confusion about how STI classes handle changes.

1 files changed, 9 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index 32e7c50588..e93e4b6e3d 100644
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -233,6 +233,15 @@ module ActiveRecord #:nodoc:
   # the companies table with type = "Firm". You can then fetch this row again using
   # <tt>Company.where(name: '37signals').first</tt> and it will return a Firm object.
   #
+  # Be aware that because the type column is an attribute on the record every new 
+  # subclass will instantly be marked as dirty and the type column will be included
+  # in the list of changed attributes on the record.  This is different from non
+  # STI classes:
+  #
+  #   Company.new.changed? # => false
+  #   Firm.new.changed? # => true
+  #   Firm.new.changes # => {"type"=>["","Firm"]}
+  #
   # If you don't have a type column defined in your table, single-table inheritance won't
   # be triggered. In that case, it'll work just like normal subclasses with no special magic
   # for differentiating between them or reloading the right type with find.