MONGOID-5234 Add Feature Flag: Remove BSON::ObjectId#as_json override (#5141)

* Revert "MONGOID-???? - Remove BSON::ObjectId#as_json as we will defer to the bson-ruby gem implementation. (#5057)"

This reverts commit e8aae8896403794285083205456489ff525dc298.

* MONGOID-5234 add feature flag for as_json

* MONGOID-5234 add docs for new feature flag

* MONGOID-5234 remove irrelevant tests and add docstring

* MONGOID-5234 add default to configuration docs

* MONGOID-5234 use dots instead of ::

* MONGOID-5234 put test back

* MONGOID-5234 update documentation and flip the flag

* MONGOID-5234 fix up as_json comment

* MONGOID-5234 update release notes

* MONGOID-5234 change method signature

Author: neilshweky

source/reference/configuration.txt

@@ -372,6 +372,14 @@ for details on driver options.
       # further information. (default: true)
       use_activesupport_time_zone: true
 
+      # In Mongoid 7.3.3 and earlier, the BSON::ObjectId#as_json method would
+      # default to returning { "$oid" => id.to_s }. Turning on this flag will
+      # defer the as_json call to bson-ruby's implementation of
+      # BSON::ObjectId#as_json. In bson-ruby 5.x.x as_json will return
+      # the id as a string. In bson-ruby 4.x.x as_json will return
+      # { "$oid" => id.to_s }. (default: false)
+      use_bson_ruby_as_json: false
+
       # Return stored times as UTC. See the time zone section below for
       # further information. Most applications should not use this option.
       # (default: false)

source/release-notes/mongoid-7.4.txt

@@ -118,6 +118,10 @@ Mongoid 7.4 and later will inherit the new implementation provided by
 ``bson-ruby`` while Mongoid 7.3 and earlier will continue with the
 implementation returning a hash of ``{"$oid" => "..."}``.
 
+..  note::
+
+  In order to get this functionality, the ``Mongoid.use_bson_ruby_as_json``
+  feature flag must be turned on.
 
 Scoped Associations
 -------------------