mongodb
diff --git a/‎source/reference/configuration.txt
Lines changed: 87 additions & 203 deletions b/‎source/reference/configuration.txt
Lines changed: 87 additions & 203 deletions
diff --git a/‎source/reference/crud.txt
Lines changed: 2 additions & 11 deletions b/‎source/reference/crud.txt
Lines changed: 2 additions & 11 deletions
@@ -286,88 +286,6 @@ for details on driver options.
       # error. (default: true)
       belongs_to_required_by_default: true
 
-      # Maintain broken behavior of sum over empty result sets for backwards
-      # compatibility. When calculating a sum on a field with a null context,
-      # for example:
-      #
-      # Product.none.sum(:price)
-      #
-      # ... return field name (`:price') instead of 0.
-      #
-      # When calculating a sum via a database query with an empty result set,
-      # for example:
-      #
-      # Product.where(impossible_condition: true).sum(:price)
-      #
-      # ... return nil instead of 0.
-      # (default: false)
-      #broken_aggregables: true
-
-      # Ignore aliased fields in embedded documents when performing pluck and
-      # distinct operations, for backwards compatibility.
-      # (default: false)
-      #broken_alias_handling: true
-
-      # Maintain broken `and' method behavior that existed in Mongoid 7.3
-      # and earlier for backwards compatibility: in some situations, conditions
-      # already present in a Criteria object would be replaced by newer
-      # conditions when `and' method is used instead of the new conditions
-      # being added to the existing conditions. This would happen when using
-      # the same operator on the same field multiple times. For example:
-      #
-      # Band.where(id: 1).and({year: {'$in' => [2020]}}, {year: {'$in' => [2021]}}).where(id: 2)
-      #
-      # yields the following criteria:
-      #
-      # <Mongoid::Criteria
-      # selector: {"_id"=>1, "year"=>{"$in"=>[2020]}, "$and"=>[{"_id"=>2}]}
-      # options:  {}
-      # class:    Band
-      # embedded: false>
-      #
-      # This is obviously incorrect as the {"$in"=>[2021]} clause is lost.
-      # Notice that the clause is only lost when both clauses are added using
-      # the #and method.
-      # (default: false)
-      #broken_and: true
-
-      # When exiting a nested `with_scope' block, set the current scope to
-      # nil instead of the parent scope for backwards compatibility.
-      # (default: false)
-      #broken_scoping: true
-
-      # Maintain broken update behavior in some cases for backwards
-      # compatibility.
-      #
-      # In Mongoid 7.3 and earlier, when assigning a value to an embedded
-      # document, then setting it to nil, then assigning the original value
-      # to it again, the second update would not work and the value for the
-      # embedded document would remain nil. Take this case:
-      #
-      # canvas.palette = palette
-      # canvas.palette = nil
-      # canvas.palette = palette
-      #
-      # ... where canvas embeds_one palette.
-      #
-      # In Mongoid 7.3 and earlier, canvas.palette would be nil when we would
-      # expect it to be palette. Set this option to true to keep this behavior,
-      # set the option to false to perform the second update correctly.
-      # (default: false)
-      #broken_updates: true
-
-      # Time objects in Ruby have nanosecond precision, whereas MongoDB server
-      # can only store times with millisecond precision. Set this option to
-      # true to truncate times to millisecond precision when performing
-      # queries on already loaded embedded associations (this is also called
-      # "embedded matching" and is done completely in Ruby), to obtain the
-      # same query results when performing time comparisons regardless of
-      # which documents are being queried. Setting this option to false will
-      # produce different results for queries on embedded associations that
-      # are already loaded into memory vs queries on unloaded associations and
-      # top-level models. (default: true)
-      #compare_time_by_ms: false
-
       # Set the global discriminator key. (default: "_type")
       discriminator_key: "_type"
 
@@ -389,21 +307,6 @@ 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
-      # false will also allow retrieving *_translations fields from pluck and
-      # distinct and will return embedded values themselves (i.e. without
-      # putting them in a hash).
-      # (default: false)
-      #legacy_pluck_distinct: true
-
       # When this flag is false, a document will become read-only only once the
       # #readonly! method is called, and an error will be raised on attempting
       # to save or update such documents, instead of just on delete. When this
@@ -412,17 +315,8 @@ for details on driver options.
       # deletable/destroyable, but will be savable/updatable.
       # When this feature flag is turned on, the read-only state will be reset on
       # reload, but when it is turned off, it won't be.
-      # (default: true)
-      legacy_readonly: false
-
-      # Maintain legacy behavior of === on Mongoid document classes, which
-      # returns true in a number of cases where Ruby's === implementation would
-      # return false. Note that the behavior of === on Mongoid document
-      # instances differs from both the behavior of === on document classes
-      # and from Ruby's behavior of === on simple object instances regardless
-      # of the value of this option.
       # (default: false)
-      #legacy_triple_equals: true
+      #legacy_readonly: true
 
       # Set the Mongoid and Ruby driver log levels when Mongoid is not using
       # Ruby on Rails logger instance. (default: :info)
@@ -432,18 +326,6 @@ for details on driver options.
       # as a BSON::Decimal128 instead of a string. (default: true)
       #map_big_decimal_to_decimal128: true
 
-      # Force ``BSON::ObjectId#as_json`` method to return the hash
-      # { "$oid" => id.to_s }. When this option is false, and bson-ruby 5
-      # is used, the return value will be the hexadecimal ObjectId string only.
-      # (default: false)
-      #object_id_as_json_oid: true
-
-      # When chaining the same operators that use the same field, setting this
-      # feature flag to false will cause those operators to be combined using an
-      # and. Setting this feature flag to true will cause the later chained
-      # operators to overwrite the earlier ones. (default: false)
-      #overwrite_chained_operators: false
-
       # Preload all models in development, needed when models use
       # inheritance. (default: false)
       preload_models: false
@@ -456,11 +338,6 @@ for details on driver options.
       # existing method. (default: false)
       scope_overwrite_exception: false
 
-      # Use ActiveSupport's time zone in time operations instead of
-      # the Ruby default time zone. See the time zone section below for
-      # further information. (default: true)
-      use_activesupport_time_zone: true
-
       # Return stored times as UTC. See the time zone section below for
       # further information. Most applications should not use this option.
       # (default: false)
@@ -469,6 +346,7 @@ for details on driver options.
       # (Deprecated) In MongoDB 4.0 and earlier, set whether to create
       # indexes in the background by default. (default: false)
       background_indexing: false
+
     # Configure driver-specific options. (optional)
     driver_options:
       # When this flag is turned off, inline options will be correctly
@@ -510,22 +388,23 @@ This way, when upgrading to a new version of Mongoid, your code will run with
 the configuration options from the previous version of Mongoid. Then,
 one-by-one, you can change the feature flags for the new version, and test that
 your code still acts as expected. Once all of the new feature flags have been
-accounted for, the call to ``load_defaults`` can be changed to take in the *new*
-version, and all of the changed feature flags can be removed. For example, say
-we're upgrading from 7.5 to 8.0. Between these two versions, only two feature
-flags were added: ``legacy_attributes`` and ``map_big_decimal_to_decimal128``.
-Before upgrading to Mongoid 8, the following line can be added:
+accounted for, the call to ``load_defaults`` may be changed to take in the *new*
+version, and all of the changed feature flags may be removed.
+
+For example, suppose we're upgrading from 7.5 to 8.0. Between these two versions,
+two feature flags were added: ``legacy_attributes`` and ``map_big_decimal_to_decimal128``.
+Before upgrading to Mongoid 8, add the following to your ``Mongoid::Config``:
 
 .. code:: ruby
 
   Mongoid.configure do |config|
     config.load_defaults 7.5
   end
 
-Now, after upgrading, those two feature flags will default to their 7.5
-functionality (``legacy_attributes: true, map_big_decimal_to_decimal128: false``).
-Now you can set these feature flags one-by-one and flip them to their 8.0
-behavior:
+After upgrading to Mongoid 8.0 in your ``Gemfile``, any feature flags will
+remain set to their 7.5 default behavior: ``legacy_attributes: true,
+map_big_decimal_to_decimal128: false``. You may then flip these feature flags
+one-by-one to their 8.0 behavior:
 
 .. code:: ruby
 
@@ -535,8 +414,8 @@ behavior:
     # config.map_big_decimal_to_decimal128 = true
   end
 
-It is advised to do these one at a time, so I have left the second flag
-commented out. After verifying your code works as expected with the
+We recommend do these one at a time, so in the example above we leave the
+second flag commented out. After verifying your code works as expected with the
 ``legacy_attributes`` flag turned off, the ``map_big_decimal_to_decimal128``
 setting can be uncommented. Once that functionality is verified as well, both
 of those lines can be removed and the ``load_defaults`` replaced with:
@@ -726,10 +605,10 @@ To set the driver logger to be the same as the Mongoid logger:
 Time Zones
 ==========
 
-Ruby has limited time zone support in the standard library. ActiveSupport
-(which Mongoid depends on) offers more comprehensive time zone support.
-Importantly, Ruby and ActiveSupport may be configured with different default
-time zones.
+Mongoid uses ActiveSupport's time zone functionality, which is far
+more robust than Ruby's standard library. Importantly, ActiveSupport
+allows configuration of ``Time.zone``, a thread-global variable which
+provides context for working with date and time values.
 
 While a thorough treatment of time zones in Ruby is outside the scope
 of this tutorial, the easiest and most reliable way of achieving correct
@@ -741,7 +620,7 @@ time zone handling is as follows:
 
   cp /usr/share/zoneinfo/UTC /etc/localtime
 
-2. Set ActiveSupport's time zone to UTC:
+2. Set your application default time zone to UTC:
 
 .. code-block:: ruby
 
@@ -753,69 +632,74 @@ time zone handling is as follows:
   # If not using Rails:
   Time.zone = 'UTC'
 
-3. Store and persist all times in UTC. Perform all calculations on times
-   in UTC.
-4. When working with user input in local time, convert such user input to UTC
-   times as soon as possible, and then work with the UTC times.
-5. When rendering or otherwise presenting times, convert them to local time
-   after performing all calculations, when actually rendering.
-6. Date to time (for example, the time when a particular day starts or ends)
-   conversions are a common source of errors. Such conversions should generally
-   be performed while explicitly specifying the time zone in which the date
-   is understood to be.
-
-Applications using Mongoid should generally configure ActiveSupport's
-time zone as described above, and then use ``Time.zone`` rather than ``Time``
-(for example, ``Time.zone.now`` instead of ``Time.now``) to invoke the
-ActiveSupport time zone machinery. This also helps achieve correct results
-when the system time zone is not UTC, as is common in development environments.
-
-Note that MongoDB stores all times in UTC without time zone information.
-
-Mongoid offers the following time zone-related configuration options:
-
-- ``use_activesupport_time_zone``: If true, prefer to work with times using
-  ``ActiveSupport::TimeWithZone``. Values in fields of type ``Time``
-  will be returned as instances of ``ActiveSupport::TimeWithZone``.
-  When parsing times without time zone information (such as when
-  mongoizing strings or arrays to time), assume the times are specified
-  in ActiveSupport's time zone. This is the default.
-
-  If false, prefer to work with times using Ruby standard library ``Time`` class.
-  Values in fields of type ``Time`` will be returned as ``Time`` instances.
-  When parsing times without time zone information, assume the times
-  are specified in the Ruby time zone.
-
-  Note that the ``use_activesupport_time_zone`` setting does not affect
-  fields of types ``Date`` or ``DateTime``, which use ``Date`` and
-  ``DateTime`` classes for their values, respectively.
-
-  Also note that Mongoid may still utilize both ``Time`` and
-  ``ActiveSupport::TimeWithZone`` classes internally, as appropriate,
-  regardless of the ``use_activesupport_time_zone`` setting.
-- ``use_utc``:
-  If true, times stored in MongoDB will be returned in UTC.
-  If false, times stored in MongoDB will be returned in local time
-  (as instances of either ``Time`` or ``ActiveSupport::TimeWithZone``,
-  respectively in the Ruby default time zone or the ActiveSupport time zone,
-  based on the value of ``use_activesupport_time_zone`` setting).
-  The default is false.
-
-  The ``use_utc`` setting does not affect how times are parsed - parsing
-  is always done in local time when the input being parsed does not
-  include time zone information. To parse dates in UTC, set the
-  system/Ruby or ActiveSupport time zone to UTC (as mentioned above,
-  setting all three to UTC leads to the fewest headaches).
-
-  Setting ``use_activesupport_time_zone`` to true and ``Time.zone`` to
-  UTC (and using ActiveSupport time machinery for all time-related
-  operations) is recommended over setting ``use_utc`` to true.
-
-Note that ``use_activesupport_time_zone`` and ``use_utc`` options do not
-throw away time zone information when it is available. For example, a Time
-instance does have an associated time zone, and this time zone will be used
-even if it is different from ActiveSupport's configured time zone when
-``use_activesupport_time_zone`` is true.
+3. In each controller and job class, set the appropriate time zone in a
+   ``before_filter`` at the earliest possible stage. As an example,
+   if each user of your application can set their own time zone,
+   you may wish to do:
+
+.. code-block:: ruby
+
+  class ApplicationController < ActionController::Base
+    before_filter :fetch_user,
+                  :set_time_zone
+
+    def set_time_zone
+      Time.zone = @user.time_zone
+    end
+  end
+
+4. From here, you may work with times naturally in the local time zone.
+   For example, in a view:
+
+.. code-block:: ruby
+
+  Turned into a pumpkin after <%= cinderella.updated_at.seconds_after_midnight %> seconds!
+
+5. Use ActiveSupport methods instead of the Ruby standard library.
+
+   - ``Time.zone.now`` or ``Time.current` instead of ``Time.now``
+   - ``Date.current`` instead of ``Date.today``
+
+   Critically, note that the latter Ruby standard library methods reference
+   your system time zone (e.g. UTC) and not the value of ``Time.zone``.
+   As it is very easy to mistake these similarly named methods, we recommend to
+   use `Rubocop's Rails/TimeZone cop
+   <https://docs.rubocop.org/rubocop-rails/cops_rails.html#railstimezone>`_ in your CI.
+
+Setting time zone on data loaded from MongoDB
+---------------------------------------------
+
+MongoDB stores all times in UTC without time zone information.
+Mongoid models load and returns time values as instances of
+``ActiveSupport::TimeWithZone``. You may set the ``use_utc`` option
+to control how Mongoid sets the time zone when loading from the database:
+
+- If false (default), Mongoid will use ``Time.zone`` to set the time
+  zone of time values are loaded from database.
+- If true, Mongoid will always set the time zone as UTC on loaded
+  time values.
+
+``use_utc`` only affects how data is loaded, and does not affect
+how data is persisted. For example, if you assign a ``Time`` or
+``ActiveSupport::TimeWithZone`` instance to a time field, the time
+zone information of the assigned instance always will be used
+irrespective of the ``use_utc`` setting. Alternatively, if you
+assign a string value to a time field, any time zone information
+in the string will be used if present. If the string does not include
+time zone information it will be parsed according to ``Time.zone``.
+To illustrate:
+
+.. code-block:: ruby
+
+  Time.use_zone("Asia/Kolkata") do
+
+    # String does not include time zone, so "Asia/Kolkata" will be used
+    ghandi.born_at = "1869-10-02 7:10 PM"
+
+    # Time zone in string (-0600) will be used
+    amelia.born_at = "1897-07-24 11:30 -0600"
+  end
+
 
 Configuring ``SSLContext``
 ==========================
 
@@ -39,17 +39,8 @@ operations with examples.
 
    * - ``Model#attributes``
 
-       *Returns a hash of the document's attributes with its values in
-       mongoized form (i.e. the way they are stored in the db).*
-
-       *In Mongoid 8.0 by default, and Mongoid 7.5 with the*
-       ``legacy_attributes`` *flag set to false, the object returned from this
-       method will have class* ``Hash``, *and have string keys. In Mongoid 7.5
-       by default, and in Mongoid 8.0 with the* ``legacy_attributes`` *flag set
-       to true, the object returned from this method will be a*
-       ``BSON::Document`` *(and thus, indifferently accessible) if the document
-       has been retrieved from the database, and a* ``Hash`` *with string keys
-       if it is a new document.*
+       *Returns the document's attributes as a ``Hash`` with string keys, and
+       its values in Mongoized form (i.e. the way they are stored in the db).*
 
        *The attributes hash also contains the attributes of all embedded
        documents, as well as their embedded documents, etc. If an embedded