Merge branch 'master' into MONGOID-5136-super-touch

Author: johnnyshields

.evergreen/config.yml

@@ -987,6 +987,69 @@ the default scope being evaluated first:
     embedded: false>
 
 
+Pagination
+==========
+
+Mongoid provides the pagination operators ``limit``, ``skip``, and ``batch_size`` on ``Criteria``.
+
+.. _limit:
+
+``limit``
+---------
+
+``limit`` sets the total number of documents to be returned by a query:
+
+.. code-block:: ruby
+
+  Band.limit(5)
+  # =>
+  # #<Mongoid::Criteria
+  #   selector: {}
+  #   options:  {:limit=>5}
+  #   class:    Band
+  #   embedded: false>
+
+.. _skip:
+
+``skip``
+--------
+
+``skip`` (alias: ``offset``) sets the number of query results to skip
+before returning documents. The ``limit`` value, if specified, will be applied
+after documents are skipped. When performing pagination, ``skip`` is recommended
+to be combined with :ref:`ordering <ordering>` to ensure consistent results.
+
+.. code-block:: ruby
+
+  Band.skip(10)
+  # =>
+  # #<Mongoid::Criteria
+  #   selector: {}
+  #   options:  {:skip=>10}
+  #   class:    Band
+  #   embedded: false>
+
+.. _batch-size:
+
+``batch_size``
+--------
+
+When executing large queries, or when iterating over query results with an enumerator method such as
+``Criteria#each``, Mongoid automatically uses the `MongoDB getMore command
+<https://docs.mongodb.com/manual/reference/command/getMore/>`_ to load results in batches.
+The default ``batch_size`` is 1000, however you may set it explicitly:
+
+.. code-block:: ruby
+
+  Band.batch_size(500)
+  # =>
+  # #<Mongoid::Criteria
+  #   selector: {}
+  #   options:  {:batch_size=>500}
+  #   class:    Band
+  #   embedded: false>
+
+
 .. _query-cache:
 
 Query Cache
@@ -1551,6 +1614,11 @@ Mongoid supports persistence operations off of criteria
 in a light capacity for when you want to expressively perform multi
 document inserts, updates, and deletion.
 
+.. warning::
+
+  Criteria ordering and pagination conditions, including ``order``, ``limit``,
+  ``offset``, and ``batch_size``, will be ignored on the following operations.
+
 .. list-table::
    :header-rows: 1
    :widths: 30 60

docs/reference/queries.txt

@@ -9,6 +9,7 @@ Release Notes
 .. toctree::
   :titlesonly:
 
+  release-notes/mongoid-7.4
   release-notes/mongoid-7.3
   release-notes/mongoid-7.2
   release-notes/mongoid-7.1

docs/release-notes.txt

@@ -0,0 +1,90 @@
+***********
+Mongoid 7.4
+***********
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+This page describes significant changes and improvements in Mongoid 7.4.
+The complete list of releases is available `on GitHub
+<https://github.com/mongodb/mongoid/releases>`_ and `in JIRA
+<https://jira.mongodb.org/projects/MONGOID?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page>`_;
+please consult GitHub releases for detailed release notes and JIRA for
+the complete list of issues fixed in each release, including bug fixes.
+
+
+``===`` Operator Matches Ruby Semantics
+---------------------------------------
+
+**Breaking change:** In Mongoid 7.4, the ``===`` operator works the same way
+as it does in Ruby, and is equivalent to calling ``is_a?`` on the right hand
+side with the left hand side as the argument:
+
+.. code-block:: ruby
+
+  ModelClass === instance
+  
+  # equivalent to:
+  instance.is_a?(ModelClass)
+
+Previously, ``===`` returned ``true`` for some cases when the equivalent Ruby
+``===`` implementation returned false.
+
+Mongoid 7.4 behavior:
+
+.. code-block:: ruby
+
+  class Band
+    include Mongoid::Document
+  end
+  
+  class CoverBand < Band
+  end
+  
+  band = Band.new
+  cover_band = CoverBand.new
+  
+  band === Band
+  # => false
+  
+  cover_band === Band
+  # => false
+  
+  Band === Band
+  # => false
+  
+  CoverBand === Band
+  # => false
+  
+Mongoid 7.3 behavior:
+
+.. code-block:: ruby
+
+  band === Band
+  # => true
+
+  cover_band === Band
+  # => true
+  
+  Band === Band
+  # => true
+  
+  CoverBand === Band
+  # => true
+
+The standard invocation of ``===``, that is having the class on the left and
+the instance on the right, works the same in Mongoid 7.4 as it did previously
+and matches the core Ruby behavior:
+
+.. code-block:: ruby
+
+  Band === band
+  # => true
+  
+  Band === cover_band
+  # => true

docs/release-notes/mongoid-7.4.txt

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require 'mongoid'
 require 'mongoid/support/query_counter'

examples/mongoid_test.rb

@@ -1,6 +1,6 @@
 source "https://rubygems.org"
 
-gem 'mongo', git: "https://github.com/mongodb/mongo-ruby-driver", branch: '2.13-stable'
+gem 'mongo', git: "https://github.com/mongodb/mongo-ruby-driver", branch: '2.14-stable'
 
 gem 'actionpack'
 

gemfiles/driver_oldstable.gemfile

@@ -3,7 +3,7 @@ source "https://rubygems.org"
 # Due to https://github.com/jruby/jruby/issues/5292 /
 # https://github.com/bundler/bundler/issues/6678 we cannot test unreleased
 # bson with JRuby, just test the driver then
-gem 'mongo', git: "https://github.com/mongodb/mongo-ruby-driver", branch: '2.13-stable'
+gem 'mongo', git: "https://github.com/mongodb/mongo-ruby-driver", branch: '2.14-stable'
 
 gem 'actionpack'
 # https://github.com/jruby/jruby/issues/6573

gemfiles/driver_oldstable_jruby.gemfile

@@ -1,6 +1,6 @@
 source "https://rubygems.org"
 
-gem 'mongo', git: "https://github.com/mongodb/mongo-ruby-driver", branch: '2.14-stable'
+gem 'mongo', git: "https://github.com/mongodb/mongo-ruby-driver", branch: '2.15-stable'
 
 gem 'actionpack'
 

gemfiles/driver_stable.gemfile

@@ -3,7 +3,7 @@ source "https://rubygems.org"
 # Due to https://github.com/jruby/jruby/issues/5292 /
 # https://github.com/bundler/bundler/issues/6678 we cannot test unreleased
 # bson with JRuby, just test the driver then
-gem 'mongo', git: "https://github.com/mongodb/mongo-ruby-driver", branch: '2.14-stable'
+gem 'mongo', git: "https://github.com/mongodb/mongo-ruby-driver", branch: '2.15-stable'
 
 gem 'actionpack'
 # https://github.com/jruby/jruby/issues/6573

gemfiles/driver_stable_jruby.gemfile

@@ -80,6 +80,12 @@ en:
             different collections so a simple id lookup is not sufficient enough."
           resolution: "Don't attempt to perform this action and have patience,
             maybe this will be supported in the future."
+        empty_config_file:
+          message: "Empty configuration file: %{path}."
+          summary: "Your mongoid.yml configuration file appears to be empty."
+          resolution: "Ensure your configuration file contains the correct contents.
+            Please consult the following page with respect to Mongoid's configuration:
+            https://docs.mongodb.com/mongoid/current/reference/configuration/"
         invalid_collection:
           message: "Access to the collection for %{klass} is not allowed."
           summary: "%{klass}.collection was called, and %{klass} is an embedded
@@ -94,6 +100,13 @@ en:
             A collation option is only supported if the query is executed on a MongoDB server
             with version >= 3.4."
           resolution: "Remove the collation option from the query."
+        invalid_config_file:
+          message: "Invalid configuration file: %{path}."
+          summary: "Your mongoid.yml configuration file does not contain the
+            correct file structure."
+          resolution: "Ensure your configuration file contains the correct contents.
+            Please consult the following page with respect to Mongoid's configuration:
+            https://docs.mongodb.com/mongoid/current/reference/configuration/"
         invalid_config_option:
           message: "Invalid configuration option: %{name}."
           summary: "A invalid configuration option was provided in your