Merge branch 'master' into uncastable-value

Author: johnnyshields

.evergreen/config.yml

@@ -763,15 +763,16 @@ buildvariants:
   tasks:
      - name: "test"
 
-- matrix_name: app-tests-jruby
-  matrix_spec:
-    jruby: ["jruby-9.3"]
-    driver: ["current"]
-    mongodb-version: '5.0'
-    topology: standalone
-    app-tests: yes
-    rails: ['6.0']
-    os: ubuntu-18.04
-  display_name: "app tests ${driver}, ${jruby}"
-  tasks:
-     - name: "test"
+# https://jira.mongodb.org/browse/MONGOID-5549
+# - matrix_name: app-tests-jruby
+#   matrix_spec:
+#     jruby: ["jruby-9.3"]
+#     driver: ["current"]
+#     mongodb-version: '5.0'
+#     topology: standalone
+#     app-tests: yes
+#     rails: ['6.0']
+#     os: ubuntu-18.04
+#   display_name: "app tests ${driver}, ${jruby}"
+#   tasks:
+#      - name: "test"

.evergreen/run-tests.sh

@@ -26,7 +26,7 @@ fi
 
 prepare_server $arch
 
-install_mlaunch_virtualenv
+install_mlaunch_venv
 
 # Launching mongod under $MONGO_ORCHESTRATION_HOME
 # makes its log available through log collecting machinery
@@ -105,7 +105,7 @@ elif test -n "$APP_TESTS"; then
   if test -z "$DOCKER_PRELOAD"; then
     ./spec/shared/bin/install-node
   fi
-  
+
   bundle exec rspec spec/integration/app_spec.rb
 else
   bundle exec rake ci

CHANGELOG.md

@@ -63,7 +63,7 @@ For instructions on upgrading to newer versions, visit
 
 * Mongoid now uses the official Mongo Ruby Driver 2.x instead of Moped.
 
-* Most driver specific configuration options have changed, please see [here](http://docs.mongodb.org/ecosystem/tutorial/ruby-driver-tutorial/#ruby-options) for the new options.
+* Most driver specific configuration options have changed, please see [here](https://www.mongodb.com/docs/ecosystem/tutorial/ruby-driver-tutorial/#ruby-options) for the new options.
 
 * All references to `session` are now replaced with `client`. This includes the mongoid.yml configuration, `store_in` options, and all exceptions and modules with `Session` in the name.
 
@@ -872,8 +872,8 @@ child elements.
   handling of validations. (Gerad Suyderhoud)
 
 * \#2443 `expire_after_seconds` is now a valid index option
-  (http://docs.mongodb.org/manual/core/indexes/#ttl-indexes,
-   http://docs.mongodb.org/manual/tutorial/expire-data/).
+  (https://www.mongodb.com/docs/manual/core/indexes/#ttl-indexes,
+   https://www.mongodb.com/docs/manual/tutorial/expire-data/).
 
         class Event
           include Mongoid::Document

LICENSE

@@ -1,5 +1,5 @@
+Copyright (c) 2015-Present MongoDB Inc.  
 Copyright (c) 2009-2016 Durran Jordan
-Copyright (c) 2015-2020 MongoDB, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -8,11 +8,11 @@ Mongoid is an ODM (Object-Document Mapper) framework for MongoDB in Ruby.
 Documentation
 -------------
 
-Mongoid has [extensive user documentation](https://docs.mongodb.com/mongoid/current/).
-[API documentation](https://docs.mongodb.com/mongoid/current/api/) is also available.
+Mongoid has [extensive user documentation](https://www.mongodb.com/docs/mongoid/current/).
+[API documentation](https://www.mongodb.com/docs/mongoid/current/api/) is also available.
 
 Mongoid is built on top of the MongoDB Ruby driver which has
-[its own user documentation](https://docs.mongodb.com/ruby-driver/current/).
+[its own user documentation](https://www.mongodb.com/docs/ruby-driver/current/).
 
 Compatibility
 -------------
@@ -39,8 +39,8 @@ Support
 License
 -------
 
+Copyright (c) 2015-Present MongoDB Inc.  
 Copyright (c) 2009-2016 Durran Jordan
-Copyright (c) 2015-2020 MongoDB, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -61,11 +61,6 @@ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-Credits
--------
-
-Durran Jordan: durran at gmail dot com
-
 [rubygems-img]: https://badge.fury.io/rb/mongoid.svg
 [rubygems-url]: http://badge.fury.io/rb/mongoid
 [inch-img]: http://inch-ci.org/github/mongodb/mongoid.svg?branch=master

SECURITY.md

@@ -15,5 +15,5 @@ currently being supported with security updates.
 
 ## Reporting a Vulnerability
 
-Please [follow the instructions here](https://docs.mongodb.com/manual/tutorial/create-a-vulnerability-report/)
+Please [follow the instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report/)
 to report a vulnerability.

docs/contributing.txt

@@ -10,3 +10,4 @@ Contributing
   :titlesonly:
 
   contributing/code-documentation
+  contributing/contributing-guidelines

docs/contributing/code-documentation.txt

@@ -35,7 +35,7 @@ Structure
     class CardboardBox
 
 - **Methods:** All method definitions should be preceded by a documentation comment.
-  Use ``@param`` and ``@return`` to specify input(s) and output respectively.
+  Use ``@param``, ``@yield``, and ``@return`` to specify inputs and output.
   For further details, refer to
   :ref:`Type Declaration <code-documentation-type-declaration>` below.
 
@@ -48,33 +48,30 @@ Structure
     # @return [ Tiger ] The transmogrified result.
     def transmogrify(person)
 
+- **Errors:** Use ``@raise`` to explain errors specific to the method.
+
+  .. code-block:: ruby
+
+    # @raise [ Errors::Validations ] If validation failed.
+    def validate!
+
 - **Private Methods:** Private methods should be documented unless they are
   so brief and straightforward that it is obvious what they do. Note that,
   for example, a method may be brief and straightforward but the type of
-  its parameter may not be obvious, in which case the parameter needs to
-  be appropriately documented.
+  its parameter may not be obvious, in which case the parameter must be
+  appropriately documented.
 
   .. code-block:: ruby
 
     private
 
     # Documentation is optional here.
-    def my_internal_method
-
-- **Notes:** Use the ``@note`` macro to explain caveats, edge cases,
-  and behavior which may surprise users.
-
-  .. code-block:: ruby
-
-    # Clear all stored data.
-    #
-    # @note This operation deletes data in the database.
-    def erase_data!
+    def do_something_obvious
 
 - **API Private:** Classes and public methods which are not intended for
   external usage should be marked ``@api private``. This macro does not
   require a comment.
-  
+
   Note that, because Mongoid's modules are mixed into application classes,
   ``private`` visibility of a method does not necessarily indicate its
   status as an API private method.
@@ -86,6 +83,18 @@ Structure
     # @api private
     def dont_call_me_from_outside
 
+- **Notes and TODOs:** Use ``@note`` to explain caveats, edge cases,
+  and behavior which may surprise users. Use ``@todo`` to record
+  follow-ups and suggestions for future improvement.
+
+  .. code-block:: ruby
+
+    # Clear all stored data.
+    #
+    # @note This operation deletes data in the database.
+    # @todo Refactor this method for performance.
+    def erase_data!
+
 - **Deprecation:** Use the ``@deprecated`` macro to indicate deprecated
   functionality. This macro does not require a comment.
 
@@ -286,3 +295,59 @@ Type Declaration
     # @option **kwargs [ String | Array<String> ] :items The items(s) as Strings to include.
     # @option **kwargs [ Integer ] :limit An Integer denoting the limit.
     def buy_groceries(**kwargs)
+
+- **Blocks:** Use ``@yield`` to specify when the method yields to a block.
+
+  .. code-block:: ruby
+
+    # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.
+    #   Must take the person, location, and weapon used. Must return true or false.
+    def whodunit
+      yield(:mustard, :ballroom, :candlestick)
+    end
+
+- **Blocks:** If the method explicitly specifies a block argument, specify the block
+  argument using ``@param`` preceded by an ampersand ``&``, and also specify ``@yield``.
+  Note ``@yield`` should be used even when method calls ``block.call`` rather than
+  ``yield`` internally.
+
+  .. code-block:: ruby
+
+    # @param &block The block.
+    # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.
+    #   Must take the person, location, and weapon used. Must return true or false.
+    def whodunit(&block)
+      yield(:scarlet, :library, :rope)
+    end
+
+    # @param &block The block.
+    # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.
+    #   Must take the person, location, and weapon used. Must return true or false.
+    def whodunit(&block)
+      block.call(:plum, :kitchen, :pipe)
+    end
+
+- **Blocks:** Use ``@yieldparam`` and ``@yieldreturn`` instead of ``@yield`` where
+  beneficial for clarity.
+
+  .. code-block:: ruby
+
+    # @param &block The block.
+    # @yieldparam [ Symbol ] The person.
+    # @yieldparam [ Symbol ] The location.
+    # @yieldparam [ Symbol ] The weapon used.
+    # @yieldreturn [ true | false ] Whether the guess is correct.
+    def whodunit(&block)
+      yield(:peacock, :conservatory, :wrench)
+    end
+
+- **Proc Args:** Proc arguments should use ``@param`` (not ``@yield``). The
+  inputs to the proc may be specified as subtype(s).
+
+  .. code-block:: ruby
+
+    # @param [ Proc<Integer, Integer, Integer> ] my_proc Proc argument which must
+    #   take 3 integers and must return true or false whether the guess is valid.
+    def guess_three(my_proc)
+      my_proc.call(42, 7, 88)
+    end

docs/contributing/contributing-guidelines.txt

@@ -0,0 +1,43 @@
+.. _contributing-guildelines:
+
+***********************
+Contributing Guidelines
+***********************
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+
+Contributing Guidelines
+=======================
+
+If you wish to propose an enhancement to Mongoid, please create a Jira ticket 
+describing the enhancement and what it would enable you to achieve in your 
+application that is not already possible. If you believe Mongoid is not 
+behaving correctly, please create a Jira ticket describing how you use Mongoid,
+what the existing behavior is that you consider incorrect or problematic, and
+what your desired behavior is. If you wish to make changes yourself, the 
+following guildelines should be followed:
+
+#. Create a fork of Mongoid.
+#. Create a new branch in that fork.
+#. Make your changes.
+#. Ensure that the proposed changes have adequate test coverage.
+#. Raise a PR against Mongoid master. If these changes correspond to a specific
+   Jira ticket, title the PR: "MONGOID-<ticket #> Description of Changes".
+#. The Mongoid team will review the PR and make comments/suggest changes.
+#. Once all of the changes and fixes are made, and the Mongoid team determine
+   the PR fit for merging, we will merge the PR into master and determine
+   whether it needs to be backported.
+#. Backports to previous stable versions are done if the change is a bug fix, 
+   is not backwards breaking, and if the commit is applicable to the 
+   corresponding stable branch. Presently backport candidates would include 
+   versions 7.3-8.0.
+#. Changes to 6.0-7.2 are generally not made unless it fixes a security
+   vulnerability.
+#. 5.x and earlier is generally not supported.

docs/installation.txt

@@ -27,7 +27,7 @@ To install the gem with bundler, include the following in your ``Gemfile``:
 
 .. code-block:: ruby
 
-   gem 'mongoid', '~> 7.3.0'
+   gem 'mongoid', '~> 9.0.0'
 
 Using Mongoid with a New Rails Application
 ==========================================