MONGOID-4852 add release notes for 7.0 and document missing features (#4747)

* read-only attribute behavior

* dependent behaviors

* $unwind in aggregation pipeline dsl

* order alphabetically

* document all Mongoid options

* reference the configuration options from everywhere they are applicable

* finish 7.0 changes

* add patch releases for 7.0

Co-authored-by: Oleg Pudeyev <oleg@bsdpower.com>

Author: p-mongo

source/tutorials/mongoid-configuration.txt

@@ -229,12 +229,37 @@ can be configured.
 
     # Configure Mongoid specific options. (optional)
     options:
+      # Application name that is printed to the mongodb logs upon establishing
+      # a connection in server versions >= 3.4. Note that the name cannot
+      # exceed 128 bytes. It is also used as the database name if the
+      # database name is not explicitly defined. (default: nil)
+      app_name: MyApplicationName
+      
+      # Create indexes in background by default. (default: false)
+      background_indexing: false
+      
+      # Mark belongs_to associations as required by default, so that saving a
+      # model with a missing belongs_to association will trigger a validation
+      # error. (default: true)
+      belongs_to_required_by_default: true
+      
+      # Raise an exception when a field is redefined. (default: false)
+      duplicate_fields_exception: false
+      
       # Include the root model name in json serialization. (default: false)
       include_root_in_json: false
 
       # Include the _type field in serialization. (default: false)
       include_type_for_serialization: false
 
+      # Whether to join nested persistence contexts for atomic operations
+      # to parent contexts by default. (default: false)
+      join_contexts: false
+
+      # Set the Mongoid and Ruby driver log levels when Mongoid is not using
+      # Ruby on Rails logger instance. (default: :info)
+      log_level: :info
+      
       # Preload all models in development, needed when models use
       # inheritance. (default: false)
       preload_models: false
@@ -257,14 +282,6 @@ can be configured.
       # (default: false)
       use_utc: false
 
-      # Set the Mongoid and Ruby driver log levels when Mongoid is not using
-      # Ruby on Rails logger instance. (default: :info)
-      log_level: :info
-      
-      # Whether to join nested persistence contexts for atomic operations
-      # to parent contexts by default. (default: false)
-      join_contexts: false
-
 The Ruby driver options may be found in 
 `the driver documentation <https://docs.mongodb.com/ruby-driver/current/tutorials/ruby-driver-create-client/>`_.
 

source/tutorials/mongoid-documents.txt

@@ -620,9 +620,41 @@ in object is a ``Point`` first, in case we also want to be able to pass in ordin
 Reserved Names
 **************
 
-If you define a field on your document that conflicts with a reserved method name in Mongoid,
-the configuration will raise an error. For a list of these you may look at
-``Mongoid.destructive_fields``.
+Attempting to define a field on a document that conflicts with a reserved
+method name in Mongoid will raise an error. The list of reserved names can
+be obtained by invoking the ``Mongoid.destructive_fields`` method.
+
+Field Redefinition
+******************
+
+By default Mongoid allows redefining fields on a model. To raise an error
+when a field is redefined, set the ``duplicate_fields_exception``
+:ref:`configuration option <configuration-options>` to ``true``.
+
+With the option set to true, the following example will raise an error:
+
+.. code-block:: ruby
+
+  class Person
+    include Mongoid::Document
+    
+    field :name
+    
+    field :name, type: String
+  end
+
+To define the field anyway, use the ``overwrite: true`` option:
+
+.. code-block:: ruby
+
+  class Person
+    include Mongoid::Document
+    
+    field :name
+    
+    field :name, type: String, overwrite: true
+  end
+
 
 Custom Ids
 **********
@@ -1005,11 +1037,14 @@ calling ``Model#previous_changes``.
    # View the previous changes.
    person.previous_changes # { "name" => [ "Alan Parsons", "Alan Garner" ] }
 
-Readonly Attributes
+.. _read-only:
+
+Read-Only Attributes
 -------------------
 
-You can tell Mongoid that certain attributes are readonly. This will allow documents to be
-created with these attributes, but changes to them will be filtered out.
+You can tell Mongoid that certain attributes are read-only. This will allow
+documents to be created with these attributes, but changes to them will be
+ignored when using mass update methods such as ``update_attributes``:
 
 .. code-block:: ruby
 
@@ -1024,8 +1059,8 @@ created with these attributes, but changes to them will be filtered out.
    band = Band.create(name: "Placebo")
    band.update_attributes(name: "Tool") # Filters out the name change.
 
-If you explicitly try to update or remove the attribute by itself, then a ``ReadonlyAttribute``
-error will be raised.
+If you explicitly try to update or remove a read-only attribute by itself,
+a ``ReadonlyAttribute`` exception will be raised:
 
 .. code-block:: ruby
 

source/tutorials/mongoid-indexes.txt

@@ -72,6 +72,10 @@ the collection is large and index creation may take a long time:
       index({ ssn: 1 }, { unique: true, background: true })
     end
 
+If the ``background_indexing`` :ref:`configuration option
+<configuration-options>` is true, the indexes are created in the background
+unless the ``background: false`` option is provided.
+
 *Deprecated:* When using MongoDB 2.6, you can drop the duplicate entries
 for unique indexes that are defined for a column that might
 already have duplicate values by specifying the ``drop_dups`` option:

source/tutorials/mongoid-persistence.txt

@@ -474,10 +474,12 @@ changes performed by each block as soon as the block ends:
   end
 
 This behavior can be changed by specifying the ``join_context: true`` option
-to ``#atomically``. When using this option, nested ``#atomically`` blocks
-are joined with the outer blocks, and only the outermost block (or the
-first block where ``join_contexts`` is false) actually writes changes to
-the cluster. For example:
+to ``#atomically``, or globally by setting the ``join_contexts``
+:ref:`configuration option <configuration-options>` to ``true``. When
+context joining is enabled, nested ``#atomically`` blocks are joined with
+the outer blocks, and only the outermost block (or the first block where
+``join_contexts`` is false) actually writes changes to the cluster.
+For example:
 
 .. code-block:: ruby
 

source/tutorials/mongoid-queries.txt

@@ -775,8 +775,11 @@ Mongoid also has some helpful methods on criteria.
 
    * - ``Criteria#find``
 
-       *Find a document or multiple documents by their ids. Will raise
-       an error by default if any of the ids do not match.*
+       *Find a document or multiple documents by their ids. If the*
+       ``raise_not_found_error`` *configuration option is set to* ``true``
+       *which is the default and any of the ids are not found, raise an error.
+       If the* ``raise_not_found_error`` *configuration option is set to*
+       ``false``, return an array of documents that have the specified ids.*
 
      -
         .. code-block:: ruby
@@ -792,9 +795,9 @@ Mongoid also has some helpful methods on criteria.
 
    * - ``Criteria#find_by``
 
-       *Find a document by the provided attributes, and if not found
-       raise an error or return nil depending on the
-       * ``raise_not_found_error`` *configuration option.*
+       *Find a document by the provided attributes. If not found,
+       raise an error or return nil depending on the value of the*
+       ``raise_not_found_error`` *configuration option.*
 
      -
         .. code-block:: ruby
@@ -1186,7 +1189,6 @@ by a provided name. Just like normal criteria, they are lazy and chainable.
 
   Band.english.rock # Get the English rock bands.
 
-
 Named scopes can take procs and blocks for accepting parameters or
 extending functionality.
 
@@ -1213,6 +1215,25 @@ extending functionality.
   Band.named("Depeche Mode") # Find Depeche Mode.
   Band.active.deutsch # Find active German bands.
 
+By default, Mongoid allows defining a scope that would shadow an existing
+class method, as the following example shows:
+
+.. code-block:: ruby
+
+  class Product
+    include Mongoid::Document
+    
+    def self.fresh
+      true
+    end
+    
+    scope :fresh, ->{ where(fresh: true) }
+  end
+
+To have Mongoid raise an error when a scope would overwrite an existing class
+method, set the ``scope_overwrite_exception`` :ref:`configuration option
+<configuration-options>` to ``true``.
+
 Default Scopes
 **************
 

source/tutorials/mongoid-relations.txt

@@ -132,8 +132,10 @@ Belongs To
 A ``belongs_to`` macro is used when a document is the child in a ``has_one``
 or ``has_many`` association. By default, in order for a document to
 be saved, each of its ``belongs_to`` associations must be provided a value.
-To override this requirement, you can use the option ``optional: false``
-on the ``belong_to`` association.
+To override this requirement for a particular association, use the option
+``optional: false`` on the ``belong_to`` association. To override this
+requirement globally, set the ``belongs_to_required_by_default``
+:ref:`configuration option <configuration-options>` to ``false``.
 
 Defining
 ~~~~~~~~
@@ -726,6 +728,8 @@ to the association.
 
   band.save # Fires all save callbacks on the band, albums, and label.
 
+.. _dependent-behavior:
+
 Dependent Behavior
 ******************
 
@@ -1149,3 +1153,115 @@ the ``_id`` field which is then used to load full models. An alternative is
 to not perform such a projection and work with raw fields, which would eliminate
 having to send the list of document ids to Mongoid in the second query
 (which could be large).
+
+.. _aggregation-pipeline-builder-dsl:
+
+Aggregation Pipeline Builder DSL
+********************************
+
+Mongoid provides limited support for constructing the aggregation pipeline
+itself using a high-level DSL. The following aggregation pipeline operators
+are supported:
+
+- `$group <https://docs.mongodb.com/manual/reference/operator/aggregation/group/>`_
+- `$project <https://docs.mongodb.com/manual/reference/operator/aggregation/project/>`_
+- `$unwind <https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/>`_
+
+To construct a pipeline, call the corresponding aggregation pipeine methods
+on a ``Criteria`` instance. Aggregation pipeline operations are added to the
+``pipeline`` attribute of the ``Criteria`` instance. To execute the pipeline,
+pass the ``pipeline`` attribute value to ``Collection#aggragegate`` method.
+
+For example, given the following models:
+
+.. code-block:: ruby
+
+  class Tour
+    include Mongoid::Document
+    
+    embeds_many :participants
+    
+    field :name, type: String
+    field :states, type: Array
+  end
+  
+  class Participant
+    include Mongoid::Document
+    
+    embedded_in :tour
+    
+    field :name, type: String
+  end
+
+We could find out which states a participant visited:
+
+.. code-block:: ruby
+
+  criteria = Tour.where('participants.name' => 'Serenity',).
+    unwind(:states).
+    group(_id: 'states', :states.add_to_set => '$states').
+    project(_id: 0, states: 1)
+  
+  pp criteria.pipeline
+  # => [{"$match"=>{"participants.name"=>"Serenity"}},
+  #     {"$unwind"=>"$states"},
+  #     {"$group"=>{"_id"=>"states", "states"=>{"$addToSet"=>"$states"}}},
+  #     {"$project"=>{"_id"=>0, "states"=>1}}]
+  
+  Tour.collection.aggregate(criteria.pipeline).to_a
+
+group
+~~~~~
+
+The ``group`` method adds a `$group aggregation pipeline stage
+<https://docs.mongodb.com/manual/reference/operator/aggregation/group/>`_.
+
+The field expressions support Mongoid symbol-operator syntax:
+
+.. code-block:: ruby
+
+    criteria = Tour.all.group(_id: 'states', :states.add_to_set => '$states')
+    criteria.pipeline
+    # => [{"$group"=>{"_id"=>"states", "states"=>{"$addToSet"=>"$states"}}}]
+
+Alternatively, standard MongoDB aggregation pipeline syntax may be used:
+
+.. code-block:: ruby
+
+    criteria = Tour.all.group(_id: 'states', states: {'$addtoSet' => '$states'})
+
+project
+~~~~~~~
+
+The ``project`` method adds a `$project aggregation pipeline stage
+<https://docs.mongodb.com/manual/reference/operator/aggregation/project/>`_.
+
+The argument should be a Hash specifying the projection:
+
+.. code-block:: ruby
+
+    criteria = Tour.all.project(_id: 0, states: 1)
+    criteria.pipeline
+    # => [{"$project"=>{"_id"=>0, "states"=>1}}]
+
+.. _unwind-dsl:
+
+unwind
+~~~~~~
+
+The ``unwind`` method adds an `$unwind aggregation pipeline stage
+<https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/>`_.
+
+The argument can be a field name, specifyable as a symbol or a string, or
+a Hash or a ``BSON::Document`` instance:
+
+.. code-block:: ruby
+
+    criteria = Tour.all.unwind(:states)
+    criteria = Tour.all.unwind('states')
+    criteria.pipeline
+    # => [{"$unwind"=>"$states"}]
+    
+    criteria = Tour.all.unwind(path: '$states')
+    criteria.pipeline
+    # => [{"$unwind"=>{:path=>"$states"}}]