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

2 files changed, 14 insertions, 0 deletions

diff --git a/activerecord/CHANGELOG b/activerecord/CHANGELOG
index 24856fa143..d8b0e2a6ff 100644
--- a/activerecord/CHANGELOG
+++ b/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] 
diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index 9e58599f81..d416773464 100755
--- a/activerecord/lib/active_record/validations.rb
+++ b/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)