DOCSP-34822: commitTxn is idempotent

source/fundamentals/crud/write-operations/insert.txt

@@ -195,7 +195,7 @@ to set with ``InsertManyOptions`` are:
 
    * - ``Ordered``
      - | If ``true``, the driver sends documents to the server in the order provided.
-         If an error occurs, the driver and server abort all remaining insert operations.
+         If an error occurs, the driver and server end all remaining insert operations.
          To learn more, see :ref:`golang-ordered-behavior`.
 
        | Default: ``false``

source/fundamentals/transactions.txt

@@ -20,23 +20,24 @@ Transactions
 Overview
 --------
 
-In this guide, you can learn how to use **transactions** with the
-{+driver-long+}. :manual:`Transactions </core/transactions/>` allow you
-to run a series of operations that do not change any data until the
-transaction is committed. If any operation in the transaction fails, the 
-driver cancels the transaction and discards all data changes before they
-ever become visible.
+In this guide, you can learn how to use the {+driver-long+} to perform
+**transactions**. :manual:`Transactions </core/transactions/>` allow
+you to run a series of operations that do not change any data until the
+transaction is committed. If any operation in the transaction returns an
+error, the driver cancels the transaction and discards all data changes
+before they ever become visible.
 
 In MongoDB, transactions run within logical **sessions**. A
-:manual:`session </reference/server-sessions/>` is a
-grouping of related read or write operations that you intend to run
-sequentially. Sessions enable :manual:`causal consistency </core/read-isolation-consistency-recency/#causal-consistency>`
-for a group of operations or allow you to execute operations in an :website:`ACID
-transaction </basics/acid-transactions>`. MongoDB guarantees that the data
-involved in your transaction operations remains consistent, even if the operations
-encounter unexpected errors.
-
-With the {+driver-short+}, you can create a new session from a
+:manual:`session </reference/server-sessions/>` is a grouping of related
+read or write operations that you intend to run sequentially. Sessions
+enable :manual:`causal consistency
+</core/read-isolation-consistency-recency/#causal-consistency>` for a
+group of operations or allow you to execute operations in an
+:website:`ACID transaction </basics/acid-transactions>`. MongoDB
+guarantees that the data involved in your transaction operations remains
+consistent, even if the operations encounter unexpected errors.
+
+When using the {+driver-short+}, you can create a new session from a
 ``Client`` instance as a ``Session`` type. We recommend that you reuse
 your client for multiple sessions and transactions instead of
 instantiating a new client each time.
@@ -45,7 +46,7 @@ instantiating a new client each time.
 
    Use a ``Session`` only with the ``Client`` (or associated
    ``Database`` or ``Collection``) that created it. Using a
-   ``Session`` with a different ``Client`` will result in operation
+   ``Session`` with a different ``Client`` results in operation
    errors.
 
 .. warning::
@@ -56,8 +57,8 @@ instantiating a new client each time.
 Methods
 -------
 
-After you start a session using the ``StartSession()`` method, you can modify
-the session state using the method set provided by the ``Session`` interface. The
+After you start a session by using the ``StartSession()`` method, you can modify
+the session state by using the method set provided by the ``Session`` interface. The
 following table describes these methods:
 
 .. list-table::
@@ -70,26 +71,41 @@ following table describes these methods:
    * - ``StartTransaction()``
      - | Starts a new transaction, configured with the given options, on
          this session. Returns an error if there is already
-         a transaction in progress for the session. For more
-         information, see the :manual:`manual entry </reference/method/Session.startTransaction/>`.
+         a transaction in progress for the session. To learn more about
+         this method, see the :manual:`startTransaction() page
+         </reference/method/Session.startTransaction/>`  in the Server manual.
        |
        | **Parameter**: ``TransactionOptions``
        | **Return Type**: ``error``
 
    * - ``AbortTransaction()``
-     - | Aborts the active transaction for this session. Returns an
+     - | Ends the active transaction for this session. Returns an
          error if there is no active transaction for the session or the
-         transaction has been committed or aborted. For more
-         information, see the :manual:`manual entry </reference/method/Session.abortTransaction/>`.
+         transaction has been committed or ended. To learn more about
+         this method, see the :manual:`abortTransaction() page
+         </reference/method/Session.abortTransaction/>`  in the Server manual.
        |
        | **Parameter**: ``Context``
        | **Return Type**: ``error``
 
    * - ``CommitTransaction()``
      - | Commits the active transaction for this session. Returns an
-         error if there is no active transaction for the session or the
-         transaction has been aborted. For more
-         information, see the :manual:`manual entry </reference/method/Session.commitTransaction/>`.
+         error if there is no active transaction for the session or if the
+         transaction was ended. To learn more about
+         this method, see the :manual:`commitTransaction() page
+         </reference/method/Session.commitTransaction/>`  in the Server manual.
+
+         .. note:: Retrying a Transaction
+
+            The ``CommitTransaction()`` method is an idempotent function, which
+            means that you can attempt to commit a transaction multiple times
+            without changing data after the first successful commit.
+
+            A transaction can succeed but return an error with the
+            ``UnknownTransactionCommitResult`` label. If you rerun the
+            ``CommitTransaction()`` method after receiving this error,
+            your data is not changed by the repeat attempts.
+
        |
        | **Parameter**: ``Context``
        | **Return Type**: ``error``
@@ -102,7 +118,7 @@ following table describes these methods:
        | **Return Type**: ``interface{}``, ``error``
 
    * - ``EndSession()``
-     - | Aborts any existing transactions and closes the session.
+     - | Ends any existing transactions and closes the session.
        |
        | **Parameter**: ``Context``
        | **Return Type**: none
@@ -133,7 +149,7 @@ following steps:
    :end-before: end-session
 
 If you require more control over your transactions, you can find an example
-showing how to manually create, commit, and abort transactions in the
+showing how to manually create, commit, and end transactions in the
 `full code example <https://raw.githubusercontent.com/mongodb/docs-golang/{+docs-branch+}/source/includes/fundamentals/code-snippets/transaction.go>`__.
 
 Additional Information