The Release Notes for Mongoid 8.1, under the section Add :replace option to #upsert, contain contradictory information. I'm assuming the first statement is an error, maybe having been written originally targeting a 9.0 release, since the subsequent information contradicts it.

The first statement is "Mongoid 8.1 adds the :replace option to the #upsert method. This option is false by default."

The next statement is "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."

Then, in the code example that follows: "player.upsert # :replace defaults to true in 8.1"

The final statement is "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."

So overall, it seems that the majority (3/4) of the statements support 8.1 using upsert: true as default. Only the first statement contradicts the rest by saying that the option is false by default.