Add documentation around nested_attrs edge case

activerecord/lib/active_record/nested_attributes.rb

@@ -236,6 +236,24 @@ class TooManyRecords < ActiveRecordError
     # of hashes can be used with hashes generated from HTTP/HTML parameters,
     # where there may be no natural way to submit an array of hashes.
     #
+    # === Updating a Collection and Its Attributes
+    # If you are passing a set of ids with your nested attributes, the
+    # attributes are executed in the order they're passed. The new
+    # records in the collection can be updated by your nested_attributes,
+    # as long as the ids are passed before the nested attributes are set.
+    #
+    #   Member.create(
+    #     name: 'rachael',
+    #     post_ids: [1],
+    #     posts_attributes: [
+    #       { id: 1, title: 'Foo' },
+    #       { title: 'Bar' }
+    #     ]
+    #   )
+    #
+    # Note: If the nested attributes are passed before the ids are set,
+    # then the ids will override all attribute changes.
+    #
     # === Saving
     #
     # All changes to models, including the destruction of those marked for

activerecord/test/cases/nested_attributes_test.rb

@@ -723,6 +723,33 @@ def test_should_automatically_build_new_associated_models_for_each_entry_in_a_ha
     assert_equal "Privateers Greed", @pirate.public_send(@association_name).last.name
   end
 
+  def test_should_include_ids_and_nested_attributes
+    bird = @pirate.public_send(@association_name).create! name: "Birb"
+    @pirate.public_send(association_id_setter, [])
+    @pirate.reload
+
+    @pirate.attributes = {
+      association_id_getter => [bird.id],
+      association_getter => [{ id: bird.id, name: "Twitter" }, { name: "Privateers Greed" }]
+    }
+
+    assert_includes @pirate.public_send(@association_name).pluck(:name), "Twitter"
+    assert_includes @pirate.public_send(@association_name).pluck(:name), "Privateers Greed"
+  end
+
+  def test_should_ids_override_nested_attributes
+    bird = @pirate.public_send(@association_name).create! name: "Birb"
+    @pirate.public_send(association_id_setter, [])
+    @pirate.reload
+
+    @pirate.attributes = {
+      association_getter => [{ name: "Privateers Greed" }],
+      association_id_getter => [bird.id],
+    }
+
+    assert_equal @pirate.public_send(@association_name).pluck(:name), ["Birb"]
+  end
+
   def test_should_not_assign_destroy_key_to_a_record
     assert_nothing_raised do
       @pirate.public_send(association_setter, "foo" => { "_destroy" => "0" })
@@ -858,6 +885,14 @@ def association_setter
     def association_getter
       @association_getter ||= "#{@association_name}_attributes".to_sym
     end
+
+    def association_id_setter
+      @association_id_setter ||= "#{@association_name.to_s.singularize}_ids=".to_sym
+    end
+
+    def association_id_getter
+      @association_id_getter ||= "#{@association_name.to_s.singularize}_ids".to_sym
+    end
 end
 
 class TestNestedAttributesOnAHasManyAssociation < ActiveRecord::TestCase