DOCS-12171: Clarify that only data-bearing members vote, hidden and delayed secondaries eligible. Stretch to clean up replica set write concern documentation

Author: ravindk89

source/core/replica-set-delayed-member.txt

@@ -56,6 +56,21 @@ When choosing the amount of delay, consider that the amount of delay:
 - must be *smaller* than the capacity of the oplog. For more
   information on oplog size, see :ref:`replica-set-oplog-sizing`.
 
+Write Concern
+~~~~~~~~~~~~~
+
+Delayed replica set members can acknowledge write operations issued
+with :writeconcern:`w: \<number\> <\<number\>>`. For write operations
+isued with :writeconcern:`w : "majority" <"majority">`, however,
+delayed members must also be voting members (i.e. 
+:rsconf:`members[n].votes` greater than ``0``) to acknowledge the 
+``"majority"`` write operation. Non-voting replica set members 
+(i.e. :rsconf:`members[n].votes` is ``0``) cannot contribute to 
+acknowledging write operations with ``majority`` write concern.
+
+Delayed secondaries can return write acknowledgment no earlier than the 
+configured :rsconf:`~members[n].slaveDelay`.
+
 Sharding
 ~~~~~~~~
 

source/core/replica-set-hidden-member.txt

@@ -50,7 +50,7 @@ Voting
 
 Hidden members *may* vote in replica set elections. If you stop a
 voting hidden member, ensure that the set has an active majority or the
-:term:`primary` will step down.
+:term:`primary` will step down. 
 
 For the purposes of backups,
 
@@ -62,6 +62,18 @@ For the purposes of backups,
 
 - .. include:: /includes/extracts/wt-fsync-lock-compatibility.rst
 
+Write Concern
+~~~~~~~~~~~~~
+
+Hidden replica set members can acknowledge write operations issued
+with :writeconcern:`w: \<number\> <\<number\>>`. For write operations
+isued with :writeconcern:`w : "majority" <"majority">`, however,
+hidden members must also be voting members (i.e. :rsconf:`members[n].votes`
+greater than ``0``) to acknowledge the ``"majority"`` write operation.
+Non-voting replica set members (i.e. :rsconf:`members[n].votes` 
+is ``0``) cannot contribute to acknowledging write operations with 
+``majority`` write concern.
+
 Further Reading
 ---------------
 

source/core/replica-set-priority-0-member.txt

@@ -12,12 +12,22 @@ Priority 0 Replica Set Members
    :depth: 1
    :class: singlecol
 
-A *priority 0* member is a secondary that **cannot** become
-:term:`primary`. *Priority 0* members cannot *trigger*
-:term:`elections <election>`.  Otherwise these members function as
-normal secondaries. A *priority 0* member maintains a copy of the data
-set, accepts read operations, and votes in elections. Configure a
-*priority 0* member to prevent :term:`secondaries <secondary>` from
+A :rsconf:`priority 0 <members[n].priority>` member is a member that
+**cannot** become :term:`primary` and **cannot** trigger
+:term:`elections <election>`. Priority 0 members can acknowledge write 
+operations issued with :ref:`write concern <write-concern>` of 
+``w : <number>``. For ``"majority"`` write concern, the priority 0 
+member must also be a voting member (i.e. :rsconf:`members[n].votes` is 
+greater than ``0``) to acknowledge the write. Non-voting replica set 
+members (i.e. :rsconf:`members[n].votes` is ``0``) cannot contribute to 
+acknowledging write operations with ``"majority"`` write concern.
+
+Other than the aforementioned restrictions, secondaries that have
+:rsconf:`priority 0 <members[n].priority>` function as normal
+secondaries: they maintains a copy of the data set, accept read
+operations, and vote in elections.
+
+Configure a secondary to have *priority 0* to prevent it from
 becoming primary, which is particularly useful in multi-data center
 deployments.
 

source/core/replica-set-rollbacks.txt

@@ -60,6 +60,8 @@ To read the contents of the rollback files, use :doc:`bsondump
 of their applications, administrators can decide the next course of
 action to take.
 
+.. _rollback-avoid:
+
 Avoid Replica Set Rollbacks
 ---------------------------
 

source/core/replica-set-write-concern.txt

@@ -10,47 +10,98 @@ Write Concern for Replica Sets
    :depth: 1
    :class: singlecol
 
-From the perspective of a client application, whether a MongoDB
-instance is running as a single server (i.e. "standalone") or a
-:term:`replica set` is transparent. However, replica sets offer some
-configuration options for write. [#sharded-clusters]_
-
-.. [#sharded-clusters] :term:`Sharded clusters <sharded cluster>` where the
-   shards are also replica sets provide the same configuration options
-   with regards to write and read operations.
-
-.. TODO: remove footnote
+:ref:`Write concern <write-concern>` for replica sets describe the 
+number of data-bearing members (i.e. the primary and secondaries, 
+but not arbiters) that must acknowledge a write operation before the
+operation returns as successful. A member can only acknowledge a 
+write operation after it has received and applied the write 
+successfully. 
+
+For replica sets, the default write concern of 
+:writeconcern:`w: 1 </<number/>>` requires that only the primary 
+replica set member acknowledge the write before returning
+write concern acknowledgment. You can specify an integer 
+value greater than ``1`` to require acknowledgment from the primary and 
+as many secondaries as needed to meet the specified value, up to the
+total number of data-bearing members in the replica set.
+
+Write operations with a write concern of :writeconcern:`"majority"` 
+require acknowledgment from a simple majority of data-bearing
+voting replica set members (i.e. :rsconf:`members[n].votes` is greater
+than ``0`` and :rsconf:`members[n].arbiterOnly` is ``false``). For
+clusters where members have :ref:`journaling <journaling-internals>`
+enabled, combining ``"majority"`` write concern with 
+:writeconcern:`j : true <j>` can prevent
+:ref:`rollback <replica-set-rollbacks>` of write concern acknowledged
+data.
+
+For complete documentation on write acknowledgment 
+behavior, see :ref:`wc-ack-behavior`. 
+
+.. include:: /images/crud-write-concern-w-majority.rst
+
+An application that issues a write operation that requires
+write concern acknowledgment waits until the primary receives
+acknowledgment from the required number of members for the specified
+write concern. For write concern of ``w`` greater than 1 or 
+``w : "majority"``, the primary waits until the required number of 
+secondaries acknowledge the write before returning write concern 
+acknowledgment. For write concern of ``w: 1``, the primary can return
+write concern acknowledgment as soon as it locally applies the write
+since it is eligible for contributing to the requested write concern. 
+
+The more members that acknowledge a write, the less likely the written 
+data could roll back if the 
+:ref:`primary fails <replication-auto-failover>`. However, specifying 
+a high write concern can increase latency as the client must wait until 
+it receives the requested level of write concern acknowledgment. 
+
+Selecting the ideal write concern for any given write operation depends
+on your application's performance goals and data durability 
+requirements. For more guidance on configuring write concern to 
+prevent rollbacks, see :ref:`rollback-avoid`.
 
 Verify Write Operations to Replica Sets
 ---------------------------------------
 
-For a replica set, the default :doc:`write concern
-</reference/write-concern>` requests acknowledgement only from the primary.
-You can, however, override this default write concern, such as to
-confirm write operations on a specified number of the replica set
-members.
-
-.. include:: /images/crud-write-concern-w2.rst
-
-To override the default write concern, specify a write concern with
-each write operation. For example, the following method includes a
-write concern that specifies that the method return only after the
-write propagates to the primary and at least one secondary or the
-method times out after 5 seconds.
+The following operation includes the ``writeConcern`` option to 
+the :method:`~db.collection.insert()` method. The operation specifies
+:writeconcern:`"majority"` write concern and a 5 second timeout using 
+the :ref:`wc-wtimeout` write concern parameter so that the operation 
+does not block indefinitely.
 
 .. code-block:: javascript
 
    db.products.insert(
       { item: "envelopes", qty : 100, type: "Clasp" },
-      { writeConcern: { w: 2, wtimeout: 5000 } }
+      { writeConcern: { w: "majority" , wtimeout: 5000 } }
    )
 
-You can include a timeout threshold for a write concern. This prevents
-write operations from blocking indefinitely if the write concern is
-unachievable. For example, if the write concern requires
-acknowledgement from 4 members of the replica set and the replica set
-has only available 3 members, the operation blocks until those members
-become available. See :ref:`wc-wtimeout`.
+The application waits until the primary returns write concern
+acknowledgment, indicating that a simple majority of data-bearing voting
+members acknowledged the write operation. For example, in a 3-member
+replica set the operation would require acknowledgment from 2 out of
+the 3 members. If the replica set was later scaled to include two 
+additional voting nodes, the same operation would require 
+acknowledgment from 3 out of the 5 replica set members. If the 
+primary does not return write concern acknowledgment within the 
+``wtimeout`` limit, the write operation fails with a write concern 
+error.
+
+A write operation that times out waiting for the specified write concern 
+only indicates that the required number of replica set members did not 
+acknowledge the write operation within the ``wtimeout`` time period.
+It does not necessarily indicate that the primary failed to apply the 
+write. The data may exist on a subset of replica set nodes at the time 
+of the write concern error, and can continue replicating until all 
+nodes in the cluster have that data. Applications should take into 
+account the potential availability of written data regardless of the 
+state of write concern acknowledgment. 
+
+The exact syntax for specifying write concern depends on the write 
+operation. Refer to the documentation for the write operation for 
+instructions on write concern support and syntax. For complete 
+documentation on write concern, see :ref:`write-concern`.
 
 .. seealso::
    :ref:`write-methods-incompatibility`

source/images/crud-write-concern-w-majority.bakedsvg.svg

@@ -0,0 +1,3 @@
+.. figure:: /images/crud-write-concern-w-majority.bakedsvg.svg
+   :alt: Write operation to a replica set with write concern level of ``w: "majority"`` or write to the primary and at least one secondary.
+   :figwidth: 520px

source/images/crud-write-concern-w-majority.rst

@@ -265,6 +265,12 @@ Replica Set Configuration Fields
       read operations (i.e. queries) from ever reaching this host by
       way of secondary :term:`read preference`.
 
+      Hidden members can acknowledge write operations
+      issued with :ref:`write-concern`. For write operations issued
+      with :writeconcern:`"majority"` write concern, the member must
+      also be a voting member (i.e. :rsconf:`~members[n].votes` is
+      greater than ``0``).
+
       .. seealso::
          :ref:`Hidden Replica Set Members <replica-set-hidden-members>`
 
@@ -292,6 +298,12 @@ Replica Set Configuration Fields
       continue to call elections until the highest priority available
       member becomes primary.
 
+      Members with :rsconf:`~members[n].priority` of ``0`` can 
+      acknowledge write operations issued with :ref:`write-concern`. 
+      For write operations issued with :writeconcern:`"majority"` write 
+      concern, the member must also be a voting member (i.e. 
+      :rsconf:`~members[n].votes` is greater than ``0``).
+
       .. seealso::
          :ref:`Replica Set Elections <replica-set-elections>`.
 
@@ -332,6 +344,14 @@ Replica Set Configuration Fields
       of the data that reflects the state of the data at some time in
       the past.
 
+      Delayed members can contribute to acknowledging write
+      operations issued with :ref:`write-concern`. However,
+      they return write acknowledgment no earlier than the configured
+      delay value. For write operations issued with 
+      :writeconcern:`"majority"` write concern, the member must also be 
+      a voting member (i.e. :rsconf:`~members[n].votes` is greater than 
+      ``0``).
+
       .. seealso::
          :doc:`/core/replica-set-delayed-member`
 
@@ -362,6 +382,9 @@ Replica Set Configuration Fields
 
       .. include:: /includes/members-used-to-allow-multiple-votes.rst
 
+      Members with ``0`` votes cannot acknowledge write operations
+      issued with a :ref:`write-concern` of :writeconcern:`majority`.
+
 ``settings``
 ~~~~~~~~~~~~