Merge branch 'master' into pr-5036

* master:
  MONGOID-5128 Scoped associations (mongodb#5017)
  MONGOID-5005 - .sum, .count, and similar aggregables now ignore sort if not limiting/skipping (mongodb#5049)
  MONGOID-5098 Improve specs for timezone handling (specs only; no behavior change) (mongodb#5023)
  MONGOID-5151 Respect aliased fields in pluck/distinct by having Document.database_field_name recursively consider embedded docs (mongodb#5047)
  RUBY-2675 test coverage on the Mongoid side (mongodb#5030)
  MONGOID-4592 Add examples of using read_attribute and write_attribute to implement custom field behavior (mongodb#5082)
  MONGOId-5185 Remove tests for _id serialization (mongodb#5081)
  MONGOID-5103 Implement eq symbol operator (mongodb#5076)
  Fix MONGOID-5006 Link default auth source documentation to driver instead of incorrectly claiming "admin" is always the default (mongodb#5048)
  Create security policy following github's template (mongodb#5070)

Author: p

SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported Versions
+
+Use this section to tell people about which versions of your project are
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 7.3     | :white_check_mark: |
+| 7.2     | :white_check_mark: |
+| 7.1     | :white_check_mark: |
+| 7.0     | :white_check_mark: |
+| < 7.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Please [follow the instructions here](https://docs.mongodb.com/manual/tutorial/create-a-vulnerability-report/)
+to report a vulnerability.

docs/reference/associations.txt

@@ -969,6 +969,61 @@ the model. However, since Mongoid doesn't know what type of data should be
 allowed in the field, the field is created with a type of Object. It is a
 good idea to explicitly define the field with the appropriate type.
 
+
+.. _association-scope:
+
+Custom Scopes
+-------------
+
+You may set a specific scope on an association using the ``:scope`` parameter.
+The scope is an additional filter that restricts which objects are considered
+to be a part of the association - a scoped association will return only
+documents which satisfy the scope condition.. The scope may be either:
+
+- a ``Proc`` with arity zero, or
+- a ``Symbol`` which references a :ref:`named scope <named-scopes>` on the
+  associated model.
+
+.. code-block:: ruby
+  class Trainer
+    has_many :pets, scope: -> { where(species: 'dog') }
+    has_many :toys, scope: :rubber
+  end
+
+  class Pet
+    belongs_to :trainer
+  end
+
+  class Toy
+    scope :rubber, where(material: 'rubber')
+    belongs_to :trainer
+  end
+
+.. note::
+
+  It is possible to add documents that do not satisfy an association's scope
+  to that association. In this case, such documents will appear associated
+  in memory, and will be saved to the database, but will not be present when
+  the association is queried in the future. For example:
+
+  .. code-block:: ruby
+
+    trainer = Trainer.create!
+    dog = Pet.create!(trainer: trainer, species: 'dog')
+    cat = Pet.create!(trainer: trainer, species: 'cat')
+
+    trainer.pets #=> [dog, cat]
+
+    trainer.reload.pets #=> [dog]
+
+.. note::
+
+  Mongoid's syntax for scoped association differs from that of Active Record.
+  Mongoid uses the ``:scope`` keyword argument for consistency with other
+  association options, whereas in Active Record the scope is a positional
+  argument.
+
+
 Validations
 -----------
 

docs/reference/configuration.txt

@@ -139,7 +139,7 @@ can be configured.
           - myhost3.mydomain.com:27017
         options:
           # These options are Ruby driver options, documented in
-          # https://docs.mongodb.com/ruby-driver/current/tutorials/ruby-driver-create-client/
+          # https://docs.mongodb.com/ruby-driver/current/reference/create-client/
 
           # Change the default write concern. (default = { w: 1 })
           write:
@@ -168,7 +168,13 @@ can be configured.
           # on 2.4 and 2.6 is :plain)
           auth_mech: :scram
 
-          # The database or source to authenticate the user against. (default: admin)
+          # Specify the auth source, i.e. the database or other source which
+          # contains the user's login credentials. Allowed values for auth source
+          # depend on the authentication mechanism, as explained in the server documentation:
+          # https://docs.mongodb.com/manual/reference/connection-string/#mongodb-urioption-urioption.authSource
+          # If no auth source is specified, the default auth source as
+          # determined by the driver will be used. Please refer to:
+          # https://docs.mongodb.com/ruby-driver/current/reference/authentication/#auth-source
           auth_source: admin
 
           # Force the driver to connect in a specific way instead of auto-
@@ -291,7 +297,7 @@ can be configured.
       use_utc: false
 
 The Ruby driver options may be found in
-`the driver documentation <https://docs.mongodb.com/ruby-driver/current/tutorials/ruby-driver-create-client/>`_.
+`the driver documentation <https://docs.mongodb.com/ruby-driver/current/reference/create-client/>`_.
 
 ERb Preprocessing
 =================
@@ -596,7 +602,7 @@ be executed sequentially during socket creation.
   in an application.
 
 For more information about TLS context hooks, including best practices for
-assigning and removing them, see `the Ruby driver documentation <https://docs.mongodb.com/ruby-driver/current/tutorials/ruby-driver-create-client/#modifying-sslcontext>`_.
+assigning and removing them, see `the Ruby driver documentation <https://docs.mongodb.com/ruby-driver/current/reference/create-client/#modifying-sslcontext>`_.
 
 Usage with Forking Servers
 ==========================

docs/reference/fields.txt

@@ -545,103 +545,14 @@ This is useful for storing different values in ``id`` and ``_id`` fields:
   # => #<Band _id: 5fc1c3f42c97a6590684046c, id: "42">
 
 
-Custom Fields
--------------
-
-You can define custom types in Mongoid and determine how they are serialized and deserialized.
-You simply need to provide three methods on it for Mongoid to call to convert your object to
-and from MongoDB friendly values.
-
-.. code-block:: ruby
-
-   class Profile
-     include Mongoid::Document
-     field :location, type: Point
-   end
-
-   class Point
-
-     attr_reader :x, :y
-
-     def initialize(x, y)
-       @x, @y = x, y
-     end
-
-     # Converts an object of this instance into a database friendly value.
-     def mongoize
-       [ x, y ]
-     end
-
-     class << self
-
-       # Get the object as it was stored in the database, and instantiate
-       # this custom class from it.
-       def demongoize(object)
-         Point.new(object[0], object[1])
-       end
-
-       # Takes any possible object and converts it to how it would be
-       # stored in the database.
-       def mongoize(object)
-         case object
-         when Point then object.mongoize
-         when Hash then Point.new(object[:x], object[:y]).mongoize
-         else object
-         end
-       end
-
-       # Converts the object that was supplied to a criteria and converts it
-       # into a database friendly form.
-       def evolve(object)
-         case object
-         when Point then object.mongoize
-         else object
-         end
-       end
-     end
-   end
-
-The instance method ``mongoize`` takes an instance of your object, and converts it
-into how it will be stored in the database. In our example above, we want to store our
-point object as an array in the form ``[ x, y ]``.
-
-The class method ``demongoize`` takes an object as how it was stored in the database,
-and is responsible for instantiating an object of your custom type. In this case, we
-take an array and instantiate a ``Point`` from it.
-
-The class method ``mongoize`` takes an object that you would use to set on your model
-from your application code, and create the object as it would be stored in the database.
-This is for cases where you are not passing your model instances of your custom type in the setter:
-
-.. code-block:: ruby
-
-   point = Point.new(12, 24)
-   venue = Venue.new(location: point) # This uses the mongoize instance method.
-   venue = Venue.new(location: [ 12, 24 ]) # This uses the mongoize class method.
-
-The class method ``evolve`` takes an object, and determines how it is to be transformed
-for use in criteria. For example we may want to write a query like so:
-
-.. code-block:: ruby
-
-   point = Point.new(12, 24)
-   Venue.where(location: point)
-
-Note that when accessing custom fields from the document, you will get a new instance
-of that object with each call to the getter. This is because Mongoid is generating a new
-object from the raw attributes on each access.
-
-We need the point object in the criteria to be transformed to a Mongo friendly value when
-it is not as well, ``evolve`` is the method that takes care of this. We check if the passed
-in object is a ``Point`` first, in case we also want to be able to pass in ordinary arrays instead.
-
 Reserved Names
 --------------
 
 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
 ------------------
 
@@ -729,6 +640,167 @@ alias can :ref:`be removed <unalias-id>` if desired (such as to integrate
 with systems that use the ``id`` field to store value different from ``_id``.
 
 
+Customizing Field Behavior
+==========================
+
+Mongoid offers several options for customizing the behavior of fields.
+
+
+Custom Getters And Setters
+--------------------------
+
+You can define custom getters and setters for fields to modify the values
+when they are being accessed or written. The getters and setters use the
+same name as the field. Use ``read_attribute`` and ``write_attribute``
+methods inside the getters and setters to operate on the raw attribute
+values.
+
+For example, Mongoid provides the ``:default`` field option to write a
+default value into the field. If you wish to have a field default value
+in your application but do not wish to persist it, you can override the
+getter as follows:
+
+.. code-block:: ruby
+
+  class DistanceMeasurement
+    include Mongoid::Document
+    
+    field :value, type: Float
+    field :unit, type: String
+    
+    def unit
+      read_attribute(:unit) || "m"
+    end
+    
+    def to_s
+      "#{value} #{unit}"
+    end
+  end
+  
+  measurement = DistanceMeasurement.new(value: 2)
+  measurement.to_s
+  # => "2.0 m"
+  measurement.attributes
+  # => {"_id"=>BSON::ObjectId('613fa0b0a15d5d61502f3447'), "value"=>2.0}
+
+To give another example, a field which converts empty strings to nil values
+may be implemented as follows:
+
+.. code-block:: ruby
+
+  class DistanceMeasurement
+    include Mongoid::Document
+    
+    field :value, type: Float
+    field :unit, type: String
+    
+    def unit=(value)
+      if value.blank?
+        value = nil
+      end
+      write_attribute(:unit, value)
+    end
+  end
+  
+  measurement = DistanceMeasurement.new(value: 2, unit: "")
+  measurement.attributes
+  # => {"_id"=>BSON::ObjectId('613fa15aa15d5d617216104c'), "value"=>2.0, "unit"=>nil}
+
+
+Custom Field Types
+------------------
+
+You can define custom types in Mongoid and determine how they are serialized
+and deserialized. You simply need to provide three methods on it for Mongoid
+to call to convert your object to and from MongoDB friendly values.
+
+.. code-block:: ruby
+
+  class Profile
+    include Mongoid::Document
+    field :location, type: Point
+  end
+
+  class Point
+
+    attr_reader :x, :y
+
+    def initialize(x, y)
+      @x, @y = x, y
+    end
+
+    # Converts an object of this instance into a database friendly value.
+    def mongoize
+      [ x, y ]
+    end
+
+    class << self
+
+      # Get the object as it was stored in the database, and instantiate
+      # this custom class from it.
+      def demongoize(object)
+        Point.new(object[0], object[1])
+      end
+
+      # Takes any possible object and converts it to how it would be
+      # stored in the database.
+      def mongoize(object)
+        case object
+        when Point then object.mongoize
+        when Hash then Point.new(object[:x], object[:y]).mongoize
+        else object
+        end
+      end
+
+      # Converts the object that was supplied to a criteria and converts it
+      # into a database friendly form.
+      def evolve(object)
+        case object
+        when Point then object.mongoize
+        else object
+        end
+      end
+    end
+  end
+
+The instance method ``mongoize`` takes an instance of your object, and
+converts it into how it will be stored in the database. In our example above,
+we want to store our point object as an array in the form ``[ x, y ]``.
+
+The class method ``demongoize`` takes an object as how it was stored in the
+database, and is responsible for instantiating an object of your custom type.
+In this case, we take an array and instantiate a ``Point`` from it.
+
+The class method ``mongoize`` takes an object that you would use to set on
+your model from your application code, and create the object as it would be
+stored in the database. This is for cases where you are not passing your
+model instances of your custom type in the setter:
+
+.. code-block:: ruby
+
+   point = Point.new(12, 24)
+   venue = Venue.new(location: point) # This uses the mongoize instance method.
+   venue = Venue.new(location: [ 12, 24 ]) # This uses the mongoize class method.
+
+The class method ``evolve`` takes an object, and determines how it is to be
+transformed for use in criteria. For example we may want to write a query
+like so:
+
+.. code-block:: ruby
+
+   point = Point.new(12, 24)
+   Venue.where(location: point)
+
+Note that when accessing custom fields from the document, you will get a
+new instance of that object with each call to the getter. This is because
+Mongoid is generating a new object from the raw attributes on each access.
+
+We need the point object in the criteria to be transformed to a
+MongoDB-friendly value when it is not as well, ``evolve`` is the method
+that takes care of this. We check if the passed in object is a ``Point``
+first, in case we also want to be able to pass in ordinary arrays instead.
+
+
 .. _dynamic-fields:
 
 Dynamic Fields