(DOCSP-28364): 7.0 downgrade policy changes (#3120)

jeff-allen-mongo · web-flow · commit 929dd2d047e5 · 2023-05-18T17:29:06.000-04:00
* WIP

* WIP

* re-add 4.2 fcv for 4.4 deployments

* update setFCV page

* re-org

* minimalism

* formatting

* minimalism

* typos

* typo

* add backward-incompatible features

* add more context to release notes

* formatting fix

* wording

* fix link location

* fix backwards-incompatible feature lead-in

* formatting
diff --git a/snooty.toml b/snooty.toml
@@ -247,6 +247,7 @@ windows-sha256 = "C777DF7816BB8C9A760FDEA782113949408B6F39D72BE29A2551FA51E2FE04
 source-available = ":github:`source available and free to use <mongodb/mongo>`"
 pcre-abbr = ":abbr:`PCRE (Perl Compatible Regular Expressions)`"
 pcre = "Perl Compatible Regular Expressions"
+fcv = ":abbr:`fCV (feature compatibility version)`"
 fts = "Atlas Search"
 # In Use Encryption Constants
 csfle = "Client-Side Field Level Encryption"
diff --git a/source/includes/list-table-featureCompatibilityVersion-defaults.rst b/source/includes/list-table-featureCompatibilityVersion-defaults.rst
@@ -5,6 +5,13 @@
    * - Deployments
      - ``featureCompatibilityVersion``
 
+   * - For new 7.0 deployments
+     - ``"7.0"``
+
+   * - For 7.0 deployments :ref:`upgraded from 6.0 <7.0-upgrade>`
+     
+     - ``"6.0"`` until you :dbcommand:`setFeatureCompatibilityVersion` to ``"7.0"``. 
+   
    * - For new 6.0 deployments
      - ``"6.0"``
 
diff --git a/source/reference/command/setFeatureCompatibilityVersion.txt b/source/reference/command/setFeatureCompatibilityVersion.txt
@@ -34,20 +34,31 @@ Definition
 Syntax
 ------
 
+.. versionchanged:: 7.0
+
 The command has the following syntax:
 
 .. code-block:: javascript
 
    db.adminCommand( 
       {
         setFeatureCompatibilityVersion: <version>,
+        confirm: true
         writeConcern: { wtimeout: <timeout> }
       } 
    )
 
 Command Fields
 --------------
 
+The ``setFeatureCompatibilityVersion`` command takes the following
+fields:
+
+setFeatureCompatibilityVersion
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Required*
+
 The possible values for ``version`` are:
 
 .. list-table::
@@ -57,8 +68,14 @@ The possible values for ``version`` are:
    * - Version
      - Description
 
+   * - ``"7.0"``
+     - *Available on MongoDB 7.0 Deployments* 
+
+       Enables the :ref:`7.0 features that persist data incompatible 
+       with MongoDB 6.0 <7.0-downgrade-considerations>`.
+
    * - ``"6.0"``
-     - *Available on MongoDB 6.0 Deployments* 
+     - *Available on MongoDB 6.0 and 7.0 Deployments* 
 
        Enables the :ref:`6.0 features that persist data incompatible 
        with MongoDB 5.0 <6.0-downgrade-considerations>`.
@@ -76,17 +93,33 @@ The possible values for ``version`` are:
        with MongoDB 4.2 <4.4-compatibility-enabled>`.
 
    * - ``"4.2"``
-     - *Available on MongoDB 4.2 and 4.4 Deployments*
+     - *Available on MongoDB 4.4 Deployments*
+
+       Disables the :ref:`4.4 features that persist data incompatible
+       with MongoDB 4.2 <4.4-compatibility-enabled>`.
+
+confirm
+~~~~~~~
 
-       Enables the :ref:`4.2 features that persist data incompatible
-       with MongoDB 4.0 <4.2-compatibility-enabled>`.
+*Required*
 
-       - If set on MongoDB 4.4 deployments,
-           Disables the :ref:`4.4 features that persist data
-           incompatible with MongoDB 4.2
-           <4.4-compatibility-enabled>`.
+.. versionadded:: 7.0
 
-The optional ``writeConcern`` specifies the write concern
+Set to ``true`` to confirm the feature compatibility change and allow
+the operation to proceed.
+
+If you omit the ``confirm`` parameter or set ``confirm`` to a value
+other than ``true``, the command fails and returns a warning about
+modifying the feature compatibility version. The warning states that
+after you upgrade or downgrade your cluster's {+fcv+}, you cannot
+downgrade the binary version without support assistance.
+
+writeConcern
+~~~~~~~~~~~~
+
+*Optional*
+
+The ``writeConcern`` specifies the write concern
 :ref:`wc-wtimeout` value in milliseconds:
 
 - The time period that the :term:`primary` waits for
@@ -105,6 +138,40 @@ The optional ``writeConcern`` specifies the write concern
 Behavior
 --------
 
+Downgrade with Backward-Incompatible Data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you try to downgrade the {+fcv+} of a cluster that contains
+incompatible data in the downloaded version, you receive a
+``CannotDowngrade`` error. When this error occurs, the cluster remains
+in the transitionary ``downgrading`` state.
+
+To move the cluster out of the ``downgrading`` state, either:
+
+- Modify your cluster data to remove backwards-incompatible features,
+  then re-run the ``setFeatureCompatibilityVersion`` command with the
+  downgraded version to set the {+fcv+} to the downgraded version.
+
+- Run the ``setFeatureCompatibilityVersion`` command with the original
+  upgraded version to set the {+fcv+} back to the original version.
+
+  .. important::
+
+     Setting the {+fcv+} to the original version stops the downgrade
+     procedure and changes the {+fcv+} back to the upgraded version.
+     This procedure does not reset the cluster back to the state before
+     the {+fcv+} downgrade began.
+
+Downgrade Policy Changes in MongoDB 7.0
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 7.0, you cannot downgrade your deployment's {+fcv+}
+to or from a :ref:`rapid release <rapid-releases>` version of MongoDB.
+
+If you upgrade or downgrade your deployment's {+fcv+}, you cannot
+downgrade your deployment's binary version without assistance from
+support.
+
 Conflicts with Background Operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -167,11 +234,12 @@ instance, run the :dbcommand:`getParameter` command on a
 
 .. code-block:: javascript
 
-   db.adminCommand( {
-                       getParameter: 1,
-                       featureCompatibilityVersion: 1
-                    }
-                  )
+   db.adminCommand(
+      {
+         getParameter: 1,
+         featureCompatibilityVersion: 1
+      }
+    )
 
 The output resembles:
 
@@ -200,6 +268,63 @@ The output resembles:
 
 .. _set-fcv:
 
+Set Feature Compatibility Version on MongoDB 7.0 Deployments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enable 7.0 Backwards Incompatible Features
+``````````````````````````````````````````
+
+To enable the :ref:`7.0 features that persist data incompatible with
+MongoDB 6.0 <7.0-downgrade-incompatible>`, set the feature compatibility
+to ``"7.0"`` on the MongoDB 7.0 deployment:
+
+.. note::
+
+   Run the :dbcommand:`setFeatureCompatibilityVersion` command against
+   the ``admin`` database.
+
+   .. include:: /includes/list-run-command-targets.rst
+
+.. code-block:: javascript
+
+   db.adminCommand(
+      {
+         setFeatureCompatibilityVersion: "7.0",
+         confirm: true
+      }
+   )
+
+Disable 7.0 Backwards Incompatible Features
+```````````````````````````````````````````
+
+To disable the :ref:`7.0 features that persist data incompatible with
+MongoDB 6.0 <7.0-downgrade-incompatible>`, set the feature compatibility
+to ``"6.0"`` on the MongoDB 7.0 deployment:
+
+.. note::
+
+   Run the :dbcommand:`setFeatureCompatibilityVersion` command against
+   the ``admin`` database.
+
+   .. include:: /includes/list-run-command-targets.rst
+
+   - ``"6.0"`` featureCompatibilityVersion is supported on MongoDB
+     6.0 and MongoDB 7.0 deployments only.
+
+.. code-block:: javascript
+
+   db.adminCommand(
+      {
+         setFeatureCompatibilityVersion: "6.0",
+         confirm: true
+      }
+   )
+
+If run as part of the downgrade process from MongoDB 7.0 to MongoDB 
+6.0, you must also remove all persisted features that are
+:ref:`incompatible <7.0-downgrade-incompatible>` with 6.0. See the
+appropriate downgrade procedures.
+
 Set Feature Compatibility Version on MongoDB 6.0 Deployments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -329,9 +454,6 @@ to ``"4.2"`` on the MongoDB 4.4 deployment:
 
    .. include:: /includes/list-run-command-targets.rst
 
-   - ``"4.2"`` featureCompatibilityVersion is supported on MongoDB
-     4.2 and MongoDB 4.4 deployments only.
-
 .. code-block:: javascript
 
    db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )
@@ -341,27 +463,6 @@ If run as part of the downgrade process from MongoDB 4.4 to MongoDB
 :ref:`incompatible <4.4-compatibility-enabled>` with 4.2. See the
 appropriate downgrade procedures.
 
-Set Feature Compatibility Version on MongoDB 4.2 Deployments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Enable 4.2 Backwards Incompatible Features
-``````````````````````````````````````````
-
-To enable the :ref:`4.2 features that persist data incompatible with
-MongoDB 4.0 <4.2-compatibility-enabled>`, set the feature compatibility
-to ``"4.2"`` on the MongoDB 4.2 deployment:
-
-.. note::
-
-   Run the :dbcommand:`setFeatureCompatibilityVersion` command against
-   the ``admin`` database.
-
-   .. include:: /includes/list-run-command-targets.rst
-
-.. code-block:: javascript
-
-   db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )
-
 Set Write Concern Timeout
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/source/reference/versioning.txt b/source/reference/versioning.txt
@@ -40,6 +40,8 @@ for MongoDB Atlas and on-premises deployments.
 - ``5.0``
 - ``6.0``
 
+.. _rapid-releases:
+
 Rapid Releases
 --------------
 
diff --git a/source/release-notes/7.0.txt b/source/release-notes/7.0.txt
@@ -91,3 +91,57 @@ OpenSSL and FIPS Support
 .. include:: /includes/ssl-and-fips-support.rst
 
 For details, see :ref:`transport-encryption`.
+
+.. _7.0-upgrade:
+
+Upgrade Procedures
+------------------
+
+.. _7.0-downgrade-considerations:
+
+Downgrade Considerations
+------------------------
+
+Downgrade Policy Changes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 7.0:
+
+- You cannot downgrade your deployment's {+fcv+} to or from a
+  :ref:`rapid release <rapid-releases>` version of MongoDB.
+
+- The :dbcommand:`setFeatureCompatibilityVersion` command requires an
+  additional parameter, ``confirm``, which must be set to ``true`` to
+  upgrade or downgrade {+fcv+}.
+
+- If you upgrade or downgrade your deployment's {+fcv+}, you cannot
+  downgrade your deployment's binary version without assistance from
+  support.
+
+.. |version| replace:: 7.0
+
+.. _7.0-downgrade-incompatible:
+
+Backward-Incompatible Features
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following 7.0 features are not compatible with earlier versions of
+MongoDB. To downgrade from MongoDB 7.0 to an earlier version, you must
+remove data that uses any of the following features:
+
+- Config shards
+
+- Secondary :ref:`TTL indexes <index-feature-ttl>` with :ref:`partial
+  filters <index-type-partial>` on :ref:`time-series collections
+  <manual-timeseries-collection>`
+
+- Time series collections with custom bucketing parameters
+
+- Collections with ``encryptedFields`` with :ref:`range indexes
+  <sharding-ranged>`
+
+- :ref:`Capped collections <manual-capped-collection>` with a size that
+  is not a multiple of 256 bytes
+
+- Config servers that have collections with
+  ``changeStreamPreAndPostImages`` enabled
