Add warning about the proper way to validate the presence of a foreign key. Closes #4147. [Francois Beausoleil <francois.beausoleil@gmail.com>]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@4285 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activerecord/CHANGELOG

@@ -1,5 +1,7 @@
 *SVN*
 
+* Add warning about the proper way to validate the presence of a foreign key. Closes #4147. [Francois Beausoleil <francois.beausoleil@gmail.com>]
+
 * Fix syntax error in documentation. Closes #4679. [mislav@nippur.irb.hr] 
 
 * Add Oracle support for CLOB inserts. Closes #4748. [schoenm@earthlink.net sandra.metz@duke.edu] 

activerecord/lib/active_record/validations.rb

@@ -386,6 +386,18 @@ module ActiveRecord
       # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
       # occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
       # method, proc or string should return or evaluate to a true or false value.
+      #
+      # === Warning
+      # Validate the presence of the foreign key, not the instance variable itself.
+      # Do this:
+      #  validate_presence_of :invoice_id
+      #
+      # Not this:
+      #  validate_presence_of :invoice
+      #
+      # If you validate the presence of the associated object, you will get
+      # failures on saves when both the parent object and the child object are
+      # new.
       def validates_presence_of(*attr_names)
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:blank], :on => :save }
         configuration.update(attr_names.pop) if attr_names.last.is_a?(Hash)