DOCS-15386 BACKPORT (#1997)

* DOCS-15386 server parameter update (#1987)

* DOCS-15386 server parameter update

* Staging updates

* Staging updates

* Staging updates

* Review feedback

* Review feedback

* Review feedback

* DOCS-15386 BACKPORT

* DOCS-15386 BACKPORT

* DOCS-15386 BACKPORT

* DOCS-15386 BACKPORT

* DOCS-15386 BACKPORT

Author: Dave Cuthbert

source/core/sharded-cluster-shards.txt

@@ -1,3 +1,5 @@
+.. _shards-concepts:
+
 ======
 Shards
 ======

source/includes/return-commit-decision-parameter.rst

@@ -1,8 +1,12 @@
-Starting in MongoDB 5.0, the new server parameter
+The server parameter
 :parameter:`coordinateCommitReturnImmediatelyAfterPersistingDecision`
 controls when transaction commit decisions are returned to the client.
-In previous versions of MongoDB, the :doc:`shard
-</core/sharded-cluster-shards>` transaction coordinator waited for all
-members to acknowledge a :ref:`multi-document transaction
+
+The parameter was introduced in MongDB 5.0 with a default value of
+``true``. In MongoDB 5.0.10 the default value changes to ``false``. 
+
+When ``coordinateCommitReturnImmediatelyAfterPersistingDecision`` is
+``false``, the :ref:`shard <shards-concepts>` transaction coordinator
+waits for all members to acknowledge a :ref:`multi-document transaction
 <transactions-atomicity>` commit before returning the commit decision to
 the client.

source/reference/parameters.txt

@@ -4337,42 +4337,64 @@ Transaction Parameters
 
 .. parameter:: coordinateCommitReturnImmediatelyAfterPersistingDecision
 
-   .. versionadded:: 5.0
+   .. versionadded:: 5.0 
+    
+   *Updated in version 5.0.10*
 
    *Type*: boolean
 
-   *Default*: true
+   *Default*: false
 
    |mongod-only|
 
-   If ``true``, the :doc:`shard </core/sharded-cluster-shards>`
-   transaction coordinator returns a :ref:`multi-document transaction
-   <transactions-atomicity>` commit decision to the client as soon as
-   the commit is made :term:`durable` with the requested transaction
-   :doc:`write concern </reference/write-concern>`. If the client
-   requested a write concern that is less than
+   Behavior When ``false``
+   ```````````````````````
+
+   The :ref:`shard <shards-concepts>` transaction coordinator waits for
+   all members to acknowledge the decision to either commit or cancel a
+   :ref:`multi-document transaction <transactions-atomicity>` before
+   returning the result to the client.
+
+   Behavior When ``true``
+   ``````````````````````
+
+   The shard transaction coordinator returns a :ref:`multi-document
+   transaction <transactions-atomicity>` commit decision to the client
+   as soon as the decision is made :term:`durable` with the requested
+   transaction :ref:`write concern <write-concern>`.
+
+   If the client requested a write concern that is less than
    :writeconcern:`"majority"`, the commit may roll back after the
    decision is returned to the client.
 
-   If ``false``, the :doc:`shard </core/sharded-cluster-shards>`
-   transaction coordinator waits for all members to acknowledge a
-   :ref:`multi-document transaction <transactions-atomicity>` commit
-   before returning the commit decision to the client.
+   Transactions may not have "read your writes" consistency. That is, a
+   read operation may not reflect the results of a write operation that
+   preceded it. This can happen in the following cases:
+
+   - A transaction has to write to multiple shards.
+   - The read and the earlier write take place in different sessions.
+
+   :ref:`Causal consistency <causal-consistency>` only guarantees the
+   causal relationship of reads and writes that occurr within the same
+   session.
+
+   Example
+   ```````
 
    The following example sets
-   :parameter:`coordinateCommitReturnImmediatelyAfterPersistingDecision`
-   to ``false``:
+   ``coordinateCommitReturnImmediatelyAfterPersistingDecision`` to
+   ``true``:
 
    .. code-block:: javascript
 
-      mongod --setParameter coordinateCommitReturnImmediatelyAfterPersistingDecision=false
+      mongod --setParameter coordinateCommitReturnImmediatelyAfterPersistingDecision=true
 
    During runtime, you can also set the parameter with the
    :dbcommand:`setParameter` command:
 
    .. code-block:: bash
 
-      db.adminCommand( { setParameter: 1, coordinateCommitReturnImmediatelyAfterPersistingDecision: false } )
+      db.adminCommand( { setParameter: 1, coordinateCommitReturnImmediatelyAfterPersistingDecision: true } )
 
 .. parameter:: transactionLifetimeLimitSeconds
 

source/release-notes/5.0-compatibility.txt

@@ -546,3 +546,12 @@ features include:
 
 - :ref:`Resharding a collection <sharding-resharding>` requires fCV set
   to 5.0+.
+
+
+Server Parameters
+-----------------
+
+Starting in MongoDB 5.0.10 the default value for
+:parameter:`coordinateCommitReturnImmediatelyAfterPersistingDecision` is
+``false``.
+