Organize 7.5 release notes

Author: p

docs/release-notes/mongoid-7.5.txt

@@ -17,104 +17,54 @@ The complete list of releases is available `on GitHub
 please consult GitHub releases for detailed release notes and JIRA for
 the complete list of issues fixed in each release, including bug fixes.
 
-``Array#update_values`` and ``Hash#update_values`` deprecated
--------------------------------------------------------------
-
-The ``Array#update_values`` and ``Hash#update_values`` methods are deprecated in
-Mongoid 7.5. It is recommended to use ActiveSupport's ``transform_values!``
-method instead.
-
-
-Ruby 2.5 Deprecated
--------------------
-
-Mongoid 7.5 deprecates support for Ruby 2.5.
-Mongoid 8 will require Ruby 2.6 or newer.
-
-
-JRuby 9.2 Deprecated
---------------------
-
-Mongoid 7.5 deprecates support for JRuby 9.2.
-Mongoid 8 will require JRuby 9.3 or newer.
-
-
-Rails 5.1 Deprecated
---------------------
-
-Mongoid 7.5 deprecates support for Rails 5.1.
-Mongoid 8 will require Rails 5.2 or newer.
-
-
-``Document#to_a`` deprecated
-----------------------------
-
-The ``Document#to_a`` method is deprecated in Mongoid 7.5.
-
-
-Combine Chained Operators Using ``and`` Instead of ``override``
----------------------------------------------------------------
-
-Mongoid 7.5 with the ``Mongoid.overwrite_chained_operators`` option set to ``false``
-will combine conditions that use the same operator and field using an ``and``.
-For example, in the following query:
-
-.. code-block:: ruby
 
-  Band.ne(name: "The Rolling Stones").ne(name: "The Beatles")
+Ruby, JRuby and Rails Version Support
+-------------------------------------
 
-Mongoid 7.5 with the ``Mongoid.overwrite_chained_operators`` option set to ``false``
-will generate the following criteria:
+Mongoid 7.5 deprecates support for Ruby 2.5, JRuby 9.2 and Rails 5.1.
+Mongoid 8 will requir Ruby 2.6 or newer, JRuby 9.3 or newer and Rails 5.2 or
+newer.
 
-.. code-block:: ruby
 
-  #<Mongoid::Criteria
-    selector: {"name"=>{"$ne"=>"The Rolling Stones"}, "$and"=>[{"name"=>{"$ne"=>"The Beatles"}}]}
-    options:  {}
-    class:    Band
-    embedded: false>
+Implemented ``Criteria#take/take!`` Method
+------------------------------------------
 
-In Mongoid 7.4 and earlier, and in 7.5 with the ``Mongoid.overwrite_chained_operators``
-option set to ``true``, the following criteria would be generated instead which
-overwrites the first condition:
+Mongoid 7.5 introduces the ``#take`` method which returns a document
+or a set of documents from the database without ordering by ``_id``:
 
-.. code-block:: ruby
+.. code:: ruby
 
-  #<Mongoid::Criteria
-    selector: {"name"=>{"$ne"=>"The Beatles"}}
-    options:  {}
-    class:    Band
-    embedded: false>
+  class Band
+    include Mongoid::Document
+  end
 
-The following functions are affected by this change:
+  Band.create!
+  Band.create!
 
-- ``eq``
-- ``elem_match``
-- ``gt``
-- ``gte``
-- ``lt``
-- ``lte``
-- ``mod``
-- ``ne``
-- ``near``
-- ``near_sphere``
+  Band.take
+  # => #<Band _id: 62c835813282a4470c07d530, >
+  Band.take(2)
+  # => [ #<Band _id: 62c835813282a4470c07d530, >, #<Band _id: 62c835823282a4470c07d531, > ]
 
-.. note::
+If a parameter is given to ``#take``, an array of documents is returned. If no parameter is
+given, a singular document is returned.
 
-   In Mongoid 7.5 with the ``Mongoid.overwrite_chained_operators`` option set to
-   ``false``, nested keys in the generated selector will always be strings,
-   whereas in Mongoid 7.4 and earlier, and in 7.5 with the
-   ``Mongoid.overwrite_chained_operators`` option set to ``true``, nested keys in
-   the selector can be strings or symbols, depending on what was passed to the
-   operator.
+The ``#take!`` method functions the same as calling ``#take`` without arguments,
+but raises an DocumentNotFound error instead of returning nil if no documents
+are found.
 
+.. code:: ruby
 
-``update_one`` Warnings in ``upsert``
--------------------------------------
+  Band.take!
+  # => #<Band _id: 62c835813282a4470c07d530, >
 
-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``.
+Note that the ``#take/take!`` methods do not apply a sort to the view before
+retrieving the documents from the database, and therefore they may return different
+results than the ``#first`` and ``#last`` methods. ``#take`` is equivalent to
+calling ``#first`` or ``#last`` with the ``{ id_sort: :none }`` option. This
+option has been deprecated in Mongoid 7.5 and it is recommended to use ``#take``
+instead going forward. Support for the ``:id_sort`` option will be dropped in
+Mongoid 8.
 
 
 Force the ``attributes`` Method to Always Return a ``Hash``
@@ -156,47 +106,6 @@ return a ``Hash`` when instantiating a new document:
   # => BSON::Document
 
 
-Implemented ``Criteria#take/take!`` Method
-------------------------------------------
-
-Mongoid 7.5 introduces the ``#take`` method which returns a document
-or a set of documents from the database without ordering by ``_id``:
-
-.. code:: ruby
-
-  class Band
-    include Mongoid::Document
-  end
-
-  Band.create!
-  Band.create!
-
-  Band.take
-  # => #<Band _id: 62c835813282a4470c07d530, >
-  Band.take(2)
-  # => [ #<Band _id: 62c835813282a4470c07d530, >, #<Band _id: 62c835823282a4470c07d531, > ]
-
-If a parameter is given to ``#take``, an array of documents is returned. If no parameter is
-given, a singular document is returned.
-
-The ``#take!`` method functions the same as calling ``#take`` without arguments,
-but raises an DocumentNotFound error instead of returning nil if no documents
-are found.
-
-.. code:: ruby
-
-  Band.take!
-  # => #<Band _id: 62c835813282a4470c07d530, >
-
-Note that the ``#take/take!`` methods do not apply a sort to the view before
-retrieving the documents from the database, and therefore they may return different
-results than the ``#first`` and ``#last`` methods. ``#take`` is equivalent to
-calling ``#first`` or ``#last`` with the ``{ id_sort: :none }`` option. This
-option has been deprecated in Mongoid 7.5 and it is recommended to use ``#take``
-instead going forward. Support for the ``:id_sort`` option will be dropped in
-Mongoid 8.
-
-
 Deprecate ``:id_sort`` Option and Support ``limit`` on ``#first/last``
 ----------------------------------------------------------------------
 
@@ -231,6 +140,63 @@ cause performance issues. To get a document without sorting first, use the
 ``Critera#take`` method.
 
 
+Combine Chained Operators Using ``and`` Instead of ``override``
+---------------------------------------------------------------
+
+Mongoid 7.5 with the ``Mongoid.overwrite_chained_operators`` option set to ``false``
+will combine conditions that use the same operator and field using an ``and``.
+For example, in the following query:
+
+.. code-block:: ruby
+
+  Band.ne(name: "The Rolling Stones").ne(name: "The Beatles")
+
+Mongoid 7.5 with the ``Mongoid.overwrite_chained_operators`` option set to ``false``
+will generate the following criteria:
+
+.. code-block:: ruby
+
+  #<Mongoid::Criteria
+    selector: {"name"=>{"$ne"=>"The Rolling Stones"}, "$and"=>[{"name"=>{"$ne"=>"The Beatles"}}]}
+    options:  {}
+    class:    Band
+    embedded: false>
+
+In Mongoid 7.4 and earlier, and in 7.5 with the ``Mongoid.overwrite_chained_operators``
+option set to ``true``, the following criteria would be generated instead which
+overwrites the first condition:
+
+.. code-block:: ruby
+
+  #<Mongoid::Criteria
+    selector: {"name"=>{"$ne"=>"The Beatles"}}
+    options:  {}
+    class:    Band
+    embedded: false>
+
+The following functions are affected by this change:
+
+- ``eq``
+- ``elem_match``
+- ``gt``
+- ``gte``
+- ``lt``
+- ``lte``
+- ``mod``
+- ``ne``
+- ``near``
+- ``near_sphere``
+
+.. note::
+
+   In Mongoid 7.5 with the ``Mongoid.overwrite_chained_operators`` option set to
+   ``false``, nested keys in the generated selector will always be strings,
+   whereas in Mongoid 7.4 and earlier, and in 7.5 with the
+   ``Mongoid.overwrite_chained_operators`` option set to ``true``, nested keys in
+   the selector can be strings or symbols, depending on what was passed to the
+   operator.
+
+
 ``Mongoid::Criteria`` cache deprecated
 --------------------------------------
 
@@ -239,3 +205,25 @@ The ability to cache individual criteria objects has been deprecated in Mongoid
 
 In order to get caching functionality, enable the Mongoid QueryCache. See the
 section on :ref:`QueryCache <query-cache>` for more details.
+
+
+``Array#update_values`` and ``Hash#update_values`` deprecated
+-------------------------------------------------------------
+
+The ``Array#update_values`` and ``Hash#update_values`` methods are deprecated in
+Mongoid 7.5. It is recommended to use ActiveSupport's ``transform_values!``
+method instead.
+
+
+``Document#to_a`` deprecated
+----------------------------
+
+The ``Document#to_a`` method is deprecated in Mongoid 7.5.
+
+
+``update_one`` Warnings in ``upsert``
+-------------------------------------
+
+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``.