Add some doc for ActiveRecord::Model

2 files changed, 38 insertions, 3 deletions

diff --git a/activerecord/CHANGELOG.md b/activerecord/CHANGELOG.md
index ee2811c2be..2c8ec3d4d1 100644
--- a/activerecord/CHANGELOG.md
+++ b/activerecord/CHANGELOG.md
@@ -1,5 +1,33 @@
 ## Rails 4.0.0 (unreleased) ##
 
+*   Added the `ActiveRecord::Model` module which can be included in a
+    class as an alternative to inheriting from `ActiveRecord::Base`:
+
+        class Post
+          include ActiveRecord::Model
+        end
+
+    Please note:
+
+      * Up until now it has been safe to assume that all AR models are
+        descendants of `ActiveRecord::Base`. This is no longer a safe
+        assumption, but it may transpire that there are areas of the
+        code which still make this assumption. So there may be
+        'teething difficulties' with this feature. (But please do try it
+        and report bugs.)
+
+      * Plugins & libraries etc that add methods to `ActiveRecord::Base`
+        will not be compatible with `ActiveRecord::Model`. Those libraries
+        should add to `ActiveRecord::Model` instead (which is included in
+        `Base`), or better still, avoid monkey-patching AR and instead
+        provide a module that users can include where they need it.
+
+      * To minimise the risk of conflicts with other code, it is
+        advisable to include `ActiveRecord::Model` early in your class
+        definition.
+
+    *Jon Leighton*
+
 *   PostgreSQL hstore records can be created.
 
 *   PostgreSQL hstore types are automatically deserialized from the database.
@@ -36,7 +64,7 @@
 *   Implemented ActiveRecord::Relation#pluck method
 
     Method returns Array of column value from table under ActiveRecord model
-        
+
         Client.pluck(:id)
 
     *Bogdan Gusiev*
@@ -53,7 +81,7 @@
       Post.find(1)
       Post.connection.close
     }.join
-    
+
     Only people who spawn threads in their application code need to worry
     about this change.
 
@@ -152,7 +180,7 @@
     during :reject_if => :all_blank (fixes #2937)
 
     *Aaron Christy*
-    
+
 ## Rails 3.1.3 (unreleased) ##
 
 *   Perf fix: If we're deleting all records in an association, don't add a IN(..) clause
diff --git a/activerecord/lib/active_record/model.rb b/activerecord/lib/active_record/model.rb
index 025f40359a..2801938729 100644
--- a/activerecord/lib/active_record/model.rb
+++ b/activerecord/lib/active_record/model.rb
@@ -1,6 +1,13 @@
 require 'active_support/deprecation'
 
 module ActiveRecord
+  # <tt>ActiveRecord::Model</tt> can be included into a class to add Active Record persistence.
+  # This is an alternative to inheriting from <tt>ActiveRecord::Base</tt>. Example:
+  #
+  #     class Post
+  #       include ActiveRecord::Model
+  #     end
+  #
   module Model
     # So we can recognise an AR class even while self.included is being
     # executed. (At that time, klass < Model == false.)