MONGOID-5318 Clarify that index background / background_indexing options are deprecated as of MongoDB 4.2 (#5249)

Co-authored-by: shields <[email protected]>

Author: johnnyshields

docs/reference/configuration.txt

@@ -260,9 +260,6 @@ for details on driver options.
       # 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)
@@ -420,6 +417,10 @@ for details on driver options.
       # (default: false)
       use_utc: false
 
+      # (Deprecated) In MongoDB 4.0 and earlier, set whether to create
+      # indexes in the background by default. (default: false)
+      background_indexing: false
+
 ERb Preprocessing
 =================
 

docs/reference/indexes.txt

@@ -61,8 +61,9 @@ Indexes can be sparse:
       index({ ssn: -1 }, { sparse: true })
     end
 
-Indexes can be specified to be created in the background in cases where
-the collection is large and index creation may take a long time:
+*Deprecated:* In MongoDB 4.0 and earlier, users could control whether to build indexes
+in the foreground (blocking) or background (non-blocking, but less efficient) using the
+``background`` option.
 
 .. code-block:: ruby
 
@@ -72,9 +73,11 @@ 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.
+The default value of ``background`` is controlled by Mongoid's
+``background_indexing`` :ref:`configuration option <configuration-options>`.
+
+The ``background`` option has `no effect as of MongoDB 4.2
+<https://www.mongodb.com/docs/manual/core/index-creation/#comparison-to-foreground-and-background-builds>`_.
 
 *Deprecated:* When using MongoDB 2.6, you can drop the duplicate entries
 for unique indexes that are defined for a column that might

lib/mongoid/config.rb

@@ -23,7 +23,8 @@ module Config
     # database name is not explicitly defined.
     option :app_name, default: nil
 
-    # Create indexes in background by default.
+    # (Deprecated) In MongoDB 4.0 and earlier, set whether to create
+    # indexes in the background by default. (default: false)
     option :background_indexing, default: false
 
     # Mark belongs_to associations as required by default, so that saving a

lib/rails/generators/mongoid/config/templates/mongoid.yml

@@ -120,9 +120,6 @@ development:
     # 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)
@@ -167,6 +164,10 @@ development:
     # (default: false)
     # use_utc: false
 
+    # (Deprecated) In MongoDB 4.0 and earlier, set whether to create
+    # indexes in the background by default. (default: false)
+    # background_indexing: false
+
 test:
   clients:
     default: