MONGOID-5363 Change #upsert to perform updating upsert rather than replacing upsert (#5492)

* MONGOID-5363 add :replace option to upsert method

* MONGOID-5363 add docs, release notes for 8.1/9.0

Author: neilshweky

source/reference/crud.txt

@@ -51,8 +51,8 @@ operations with examples.
        has been retrieved from the database, and a* ``Hash`` *with string keys
        if it is a new document.*
 
-       *The attributes hash also contains the attributes of all embedded 
-       documents, as well as their embedded documents, etc. If an embedded 
+       *The attributes hash also contains the attributes of all embedded
+       documents, as well as their embedded documents, etc. If an embedded
        association is empty, its key will not show up in the returned hash.*
 
      -
@@ -224,9 +224,12 @@ operations with examples.
    * - ``Model#upsert``
 
        *Performs a MongoDB replace with upsert on the document. If the document
-       exists in the database, it will get overwritten with the current
-       document in the application (any attributes present in the database but
-       not in the application's document instance will be lost).
+       exists in the database and the* ``:replace`` *option is set to true, it
+       will get overwritten with the current document in the application (any
+       attributes present in the database but not in the application's document
+       instance will be lost). If the* ``:replace`` *option is false (default),
+       the document will be updated, and any attributes not in the application's
+       document will be maintained.
        If the document does not exist in the database, it will be inserted.
        Note that this only runs the* ``{before|after|around}_upsert`` *callbacks.*
      -
@@ -237,6 +240,7 @@ operations with examples.
             last_name: "Heine"
           )
           person.upsert
+          person.upsert(replace: true)
 
    * - ``Model#touch``
 

source/release-notes.txt

@@ -9,6 +9,7 @@ Release Notes
 .. toctree::
   :titlesonly:
 
+  release-notes/mongoid-9.0
   release-notes/mongoid-8.1
   release-notes/mongoid-8.0
   release-notes/mongoid-7.5

source/release-notes/mongoid-8.1.txt

@@ -300,3 +300,44 @@ An _id, a hash of conditions, or ``false``/``nil`` can now be included:
   Band.exists?(BSON::ObjectId('6320d96a3282a48cfce9e72c'))
   Band.exists?(false) # always false
   Band.exists?(nil) # always false
+
+
+Added ``:replace`` option to ``#upsert``
+----------------------------------------
+
+Mongoid 8.1 adds the ``:replace`` option to the ``#upsert`` method. This option
+is ``false`` by default.
+
+In Mongoid 8 and earlier, and in Mongoid 8.1 when passing ``replace: true``
+(the default) the upserted document will overwrite the current document in the
+database if it exists. Consider the following example:
+
+.. code:: ruby
+
+  existing = Player.create!(name: "Juan Soto", age: 23, team: "WAS")
+
+  player = Player.new(name: "Juan Soto", team: "SD")
+  player.id = existing.id
+  player.upsert # :replace defaults to true in 8.1
+
+  p Player.find(existing.id)
+  # => <Player _id: 633b42f43282a45fadfaaf9d, name: "Juan Soto", age: nil, team: "SD">
+
+As you can see, the value for the ``:age`` field was dropped, because the
+upsert replaced the entire document instead of just updating it. If we take the
+same example and set ``:replace`` to ``false``, however:
+
+.. code:: ruby
+
+  player.upsert(replace: false)
+
+  p Player.find(existing.id)
+  # => <Player _id: 633b42f43282a45fadfaaf9d, name: "Juan Soto", age: 23, team: "SD">
+
+This time, the value for the ``:age`` field is maintained.
+
+.. note::
+
+  The default for the ``:replace`` option will be changed to ``false`` in
+  Mongoid 9.0, therefore it is recommended to explicitly specify this option
+  while using ``#upsert`` in 8.1 for easier upgradability.

source/release-notes/mongoid-9.0.txt

@@ -73,3 +73,16 @@ the type conversion.
 Note that in prior Mongoid versions, typecasting Date to Time during
 persistence operations was already correctly using the
 ``Mongoid.use_activesupport_time_zone`` setting.
+
+
+Flipped default for ``:replace`` option in ``#upsert``
+------------------------------------------------------
+
+Mongoid 8.1 added the ``:replace`` option to the ``#upsert`` method. This
+option was used to specify whether or not the existing document should be
+updated or replaced.
+
+Mongoid 9.0 flips the default of this flag from ``true`` => ``false``.
+
+This means that, by default, Mongoid 9 will update the existing document and
+will not replace it.