MONGOID-5365 Change #attributes return value to Hash with a flag (#5301)

* MONGOID-5365 Change #attributes return value to Hash with a flag

* MONGOID-5365 add config_override to tests

* MONGOID-5365 rename flag and flip default

* MONGOID-5365 fix old flag ref

Author: neilshweky

source/reference/configuration.txt

@@ -368,6 +368,12 @@ for details on driver options.
       # to parent contexts by default. (default: false)
       join_contexts: false
 
+      # When this flag is true, the attributes method on a document will return
+      # a BSON::Document when that document is retrieved from the database, and
+      # a Hash otherwise. When this flag is false, the attributes method will
+      # always return a Hash. (default: false)
+      #legacy_attributes: true
+
       # Maintain legacy behavior of pluck and distinct, which does not demongoize
       # values on returning them. Setting this option to false will cause
       # pluck and distinct to return demongoized values. Setting this option to

source/release-notes/mongoid-7.5.txt

@@ -87,3 +87,42 @@ The following functions are affected by this change:
 Mongoid 7.5 fixes incorrect usage of the driver's ``update_one`` method from
 Mongoid's ``upsert`` method. Mongoid's ``upsert`` actually performs a
 replacing upsert, and Mongoid 7.5 correctly calls ``replace_one``.
+
+
+Force the ``attributes`` Method to Always Return a ``Hash``
+```````````````````````````````````````````````````````````
+
+Mongoid 7.5 with the ``Mongoid.legacy_attributes`` option set to ``false``
+will always return a ``Hash`` when calling the ``attributes`` method.
+For example:
+
+.. code-block:: ruby
+
+  class Band
+    include Mongoid::Document
+
+    field :name
+  end
+
+  band = Band.create!(name: "The Rolling Stones")
+  p band.attributes.class
+  # => Hash
+
+  band = Band.first
+  p band.attributes.class
+  # => Hash
+
+In Mongoid 7.4 and earlier, and in 7.5 with the ``Mongoid.legacy_attributes``
+option set to ``true``, the ``attributes`` method on a document will return a
+``BSON::Document`` when retrieving that document from the database, but will
+return a ``Hash`` when instantiating a new document:
+
+.. code-block:: ruby
+
+  band = Band.create!(name: "The Rolling Stones")
+  p band.attributes.class
+  # => Hash
+
+  band = Band.first
+  p band.attributes.class
+  # => BSON::Document

source/release-notes/mongoid-8.0.txt

@@ -31,17 +31,18 @@ Default Option Values Changed
 **Breaking change:** The following options have had their default values
 changed in Mongoid 8.0:
 
-- ``:overwrite_chained_operators`` => ``false``
 - ``:broken_aggregables`` => ``false``
 - ``:broken_alias_handling`` => ``false``
 - ``:broken_and`` => ``false``
 - ``:broken_scoping`` => ``false``
 - ``:broken_updates`` => ``false``
 - ``:compare_time_by_ms`` => ``true``
+- ``:legacy_attributes`` => true
 - ``:legacy_pluck_distinct`` => ``false``
 - ``:legacy_triple_equals`` => ``false``
 - ``:map_big_decimal_to_decimal128`` => ``true``
 - ``:object_id_as_json_oid`` => ``false``
+- ``:overwrite_chained_operators`` => ``false``
 
 Please refer to :ref:`configuration option <configuration-options>` for
 the description and effects of each of these options.