chore(DRIVERS-2134): clarify write concern options in txn (#1712)

Author: durran

source/transactions/tests/README.md

@@ -76,6 +76,22 @@ driver, use command monitoring instead.
 3. Test that `PoolClearedError` has `TransientTransactionError` label. Since there is no simple way to trigger
     `PoolClearedError`, this test should be implemented in a way that suites each driver the best.
 
+## Options Inside Transaction Prose Tests.
+
+These prose tests ensure drivers handle options inside a transaction where the unified tests do not suffice. Ensure
+these tests do not run against a standalone server.
+
+### 1.0 Write concern not inherited from collection object inside transaction.
+
+- Create a MongoClient running against a configured sharded/replica set/load balanced cluster.
+- Start a new session on the client.
+- Start a transaction on the session.
+- Instantiate a collection object in the driver with a default write concern of `{ w: 0 }`.
+- Insert the document `{ n: 1 }` on the instantiated collection.
+- Commit the transaction.
+- End the session.
+- Ensure the document was inserted and no error was thrown from the transaction.
+
 ## Changelog
 
 - 2024-10-31: Add test for PoolClearedError.

source/transactions/transactions.md

@@ -203,6 +203,19 @@ Drivers MUST raise an error if the user provides or if defaults would result in
 Driver Sessions spec disallows using unacknowledged writes in a session. The error message MUST contain "transactions do
 not support unacknowledged write concerns".
 
+If a higher level object, such as a Collection, is created inside a transaction, their write concern option MUST be
+ignored if provided and the transaction level write concern used instead. An example of expected behaviour is:
+
+```python
+client = MongoClient("mongodb://host/?readPreference=nearest")
+coll = client.db.test
+with client.start_session() as s:
+    with s.start_transaction():
+        w_0_coll = db.get_collection("w_0_coll", writeConcern=WriteConcern(w=0))
+        # This is allowed, the write concern of the transaction is used instead of w=0 from the collection.
+        w_0_coll.insert_one({}, session=s)
+```
+
 #### readPreference
 
 The read preference to use for all read operations in this transaction.
@@ -1074,6 +1087,8 @@ objective of avoiding duplicate commits.
 
 ## **Changelog**
 
+- 2024-11-01: Clarify collection options inside txn.
+
 - 2024-11-01: Specify that ClientSession must be unpinned when ended.
 
 - 2024-10-31: Clarify when drivers must add TransientTransactionError label.