DOCSP-36046 Transaction FindOneAndUpdate Doesn't Lock Document (#6100) (#6733)

* DOCSP-36046 Transaction FindOneAndUpdate Doesn't Lock Document

* wording

* IF feedback: add stale reads to glossary, add procedure steps

* formatting

* typo

* *

* IF suggestions

* io code block

* typo

* hide default visibility

* nit edit

* AK feedback

* wording

* *

* *

* *

* Asya feedback

* Asya feedback 2/2

* final feedback

Author: ajhuh-mdb

source/core/read-preference-use-cases.txt

@@ -53,8 +53,8 @@ read preference modes:
 
   Use :readmode:`primaryPreferred` if you want an application to
   read from the primary under normal circumstances, but to
-  allow stale reads from secondaries when the primary is unavailable. This provides a
-  "read-only mode" for your application during a failover.
+  allow :term:`stale reads <stale read>` from secondaries when the primary is 
+  unavailable. 
 
 .. _read-preference-counter-indications:
 

source/includes/extracts-transactions.yaml

@@ -207,37 +207,87 @@ content: |
 ref: transactions-stale-reads
 content: |
 
-   Read operations inside a transaction can return stale data. That is,
-   read operations inside a transaction are not guaranteed to see
-   writes performed by other committed transactions or
-   non-transactional writes. For
-   example, consider the following sequence: 1) a transaction is
-   in-progress 2) a write outside the transaction deletes a document 3)
-   a read operation inside the transaction is able to read the
-   now-deleted document since the operation is using a snapshot from
-   before the write.
+   Read operations inside a transaction can return old data, which is known as a
+   :term:`stale read`. Read operations inside a transaction are not guaranteed 
+   to see writes performed by other committed transactions or
+   non-transactional writes. For example, consider the following sequence: 
+   
+   #. A transaction is in-progress.
+   
+   #. A write outside the transaction deletes a document. 
+   
+   #. A read operation inside the transaction can read the now-deleted document 
+      since the operation uses a snapshot from before the write operation.
 
    To avoid stale reads inside transactions for a single document, you
-   can use the :method:`db.collection.findOneAndUpdate()` method. For
-   example:
-
-   .. code-block:: javascript
-
-      session.startTransaction( { readConcern: { level: "snapshot" }, writeConcern: { w: "majority" } } );
-
-      employeesCollection = session.getDatabase("hr").employees;
-
-      employeeDoc = employeesCollection.findOneAndUpdate( 
-         { _id: 1, employee: 1, status: "Active" },
-         { $set: { employee: 1 } },
-         { returnNewDocument: true }
-      );
-
-   - If the employee document has changed outside the transaction, then
-     the transaction aborts.
+   can use the :method:`db.collection.findOneAndUpdate()` method. The following 
+   :binary:`~bin.mongosh` example demonstrates how you can use 
+   ``db.collection.findOneAndUpdate()`` to take a :term:`write lock` and ensure 
+   that your reads are up to date:
+
+   .. procedure::
+        :style: normal
+
+        .. step:: Insert a document into the ``employees`` collection
+           
+           .. code-block:: javascript
+              :copyable: true 
+           
+              db.getSiblingDB("hr").employees.insertOne(
+                 { _id: 1, status: "Active" }
+              )
+
+        .. step:: Start a session
+
+           .. code-block:: javascript
+              :copyable: true 
+              
+              session = db.getMongo().startSession( { readPreference: { mode: "primary" } } )
+
+        .. step:: Start a transaction 
+         
+           .. code-block:: javascript
+              :copyable: true 
+             
+              session.startTransaction( { readConcern: { level: "snapshot" }, writeConcern: { w: "majority" } } )
+             
+              employeesCollection = session.getDatabase("hr").employees
+
+        .. step:: Use ``db.collection.findOneAndUpdate()`` inside the transaction
+         
+           .. code-block:: javascript
+              :copyable: true 
+             
+              employeeDoc = employeesCollection.findOneAndUpdate( 
+                 { _id: 1, status: "Active" },
+                 { $set: { lockId: ObjectId() } },
+                 { returnNewDocument: true }
+              )
+
+           Note that inside the transaction, the ``findOneAndUpdate`` operation 
+           sets a new ``lockId`` field. You can set ``lockId`` field to any 
+           value, as long as it modifies the document. By updating the 
+           document, the transaction acquires a lock.
+           
+           If an operation outside of the transaction attempts to modify the 
+           document before you commit the transaction, MongoDB returns a write 
+           conflict error to the external operation.
+
+        .. step:: Commit the transaction
+        
+           .. code-block:: javascript
+              :copyable: true         
+              
+              session.commitTransaction()
+
+           After you commit the transaction, MongoDB releases the lock.
+           
+           .. note:: 
+           
+              If any operation in the transaction fails, the transaction 
+              aborts and all data changes made in the transaction are discarded
+              without ever becoming visible in the collection.
 
-   - If the employee document has not changed, the transaction returns
-     the document and locks the document.
 ---
 ref: transactions-read-concern-majority
 content: |

source/reference/glossary.txt

@@ -1063,6 +1063,11 @@ Glossary
       state electronics for persistence instead of rotating platters
       and movable read/write heads used by mechanical hard drives.
 
+   stale read
+      A stale read refers to when a transaction reads old (stale) data that has 
+      been modified by another transaction but not yet committed to the 
+      database. 
+   
    standalone
       An instance of :binary:`~bin.mongod` that runs as a single server
       and not as part of a :term:`replica set`. To convert it to a