Suggested edit to make clear what a quorum actually represents. by oliverdain · Pull Request #252 · apache/couchdb-documentation

oliverdain · 2018-02-27T23:34:09Z

Overview

I found the documentation about read and write quorums for a cluster mode DB confusing. I think this edit makes things a bit more clear (though I don't love the wording).

This came from a Slack conversation which you can find here if curious: https://couchdb.slack.com/archives/C49LEE7NW/p1519761842000347

flimzy

I applaud the attempt at clarity. Unfortunately, the edit isn't very clear to me--the first paragraph in particular.

flimzy · 2018-03-01T08:17:03Z

-save a document before a write is returned with ``201``. If there are less
-nodes than that number, then ``202`` is returned. Both read and write numbers
-can be specified with a request as ``r`` and ``w`` parameters accordingly.
+the document plus one *in the current partition*. That is, if there is a network


"partition" is not a word common to CouchDB parlance. Do you mean node? shard?

I was trying to describe a network partition. Specifically, here I'm trying to say that if there's a network partition then the quorum is relative to only the subset of nodes on the side of the partition where the client is.

Definitely open to different wording if this is confusing.

Ah, now I see what you're getting at. That is an important point. And the paragraph was already a bit confusing before your addition. Perhaps a rewrite of the entire section is in order.

Example:

In clustered operation, a quorum must be reached before CouchDB returns a 200 for a fetch, or 201 for a write operation. A quorum is defined one plus half the number of copies.

For read operations, the maximum number of copies is the number of currently-accessible nodes, meaning that in the case of a failure or network partition, the effective number of copies may be lower. The number of read copies can be set with the rparameter.

For write operations, the number of copies can be set using the w parameter. If fewer than this number of nodes is available, a 202 will be returned.

Overall I like what you have better. Will start with that but make a few changes to be more explicit. Updated PR coming soon...

flimzy · 2018-03-01T08:18:57Z

+The number of nodes that need to save a document before a write is returned with
+``201`` is also equal to half of the total copies of the document plus one.
+However, unlike the read case, for writes this is computed for the database as a
+whole, even if there is a network partition. If there are less nodes than that


"less" -> "fewer" to satisfy the grammar nazis

oliverdain · 2018-03-01T18:22:57Z

Thanks for the review @flimzy . Made the obvious grammar fix. Not entirely sure how to fix the 1st paragraph. Would love suggestions.

oliverdain · 2018-03-05T00:24:07Z

OK. Ready for re-review. Thanks @flimzy

flimzy

I like this wording much better! Well done. Just a few minor fixes remaining.

flimzy · 2018-03-05T07:27:04Z

-nodes than that number, then ``202`` is returned. Both read and write numbers
-can be specified with a request as ``r`` and ``w`` parameters accordingly.
+In clustered operation, a quorum must be reached before CouchDB returns a 200
+for a fetch, or 201 for a write operation. A quorum is defined one plus half the


A quorum is defined as one...

flimzy · 2018-03-05T07:27:27Z

-save a document before a write is returned with ``201``. If there are less
-nodes than that number, then ``202`` is returned. Both read and write numbers
-can be specified with a request as ``r`` and ``w`` parameters accordingly.
+In clustered operation, a quorum must be reached before CouchDB returns a 200


Probably good idea to wrap status codes with tick marks as before:

``200``

vs

200

flimzy · 2018-03-05T07:28:22Z

+set with the rparameter.
+
+For write operations the number of relevant copies is always `n`, the number of
+replicas in teh cluster.  For write operations, the number of copies can be set


oliverdain · 2018-03-05T18:14:43Z

All fixed. Thanks for the review.

flimzy · 2018-03-05T19:43:52Z

+1

oliverdain · 2018-03-05T19:45:59Z

@flimzy what's your process? Do you do the merge or should I do that?

Thanks again for the review.

oliverdain · 2018-03-15T17:56:58Z

Hey @flimzy thanks again for your review here. I noticed the live docs haven't changed yet (http://docs.couchdb.org/en/2.1.1/cluster/theory.html). I kinda thought when this was merged the docs would auto-update. Is that not the case?

wohali · 2018-03-15T18:29:12Z

Hi @oliverdain ,

The documentation for a specific release (such as 2.1.1) are invariant; they are tagged at the time of the official Apache CouchDB release and updates cannot be made.

You can see your updates here: http://docs.couchdb.org/en/master/cluster/theory.html

In addition, the next release of CouchDB (2.2.0) will include your changes. This release is Very Soon Now(tm).

Thanks again for your contribution!

…s. (#252)" This reverts commit 4eabf79. This notion of different quorums for doc read vs doc write is not true.

…s. (#252)" (#610) This reverts commit 4eabf79. This notion of different quorums for doc read vs doc write is not true.

Suggested edit to make clear what a quorum actually represents.

87ba2ed

flimzy reviewed Mar 1, 2018

View reviewed changes

Fix as per code review.

2182aaf

More changes per code review.

d1d6d28

flimzy suggested changes Mar 5, 2018

View reviewed changes

Fixed minor typos per PR

3a0f5c2

flimzy approved these changes Mar 5, 2018

View reviewed changes

Merge branch 'master' into master

5c33716

flimzy merged commit 4eabf79 into apache:master Mar 8, 2018

rnewson added a commit that referenced this pull request Dec 15, 2020

Revert "Suggested edit to make clear what a quorum actually represent…

2a80b50

…s. (#252)" This reverts commit 4eabf79. This notion of different quorums for doc read vs doc write is not true.

rnewson added a commit that referenced this pull request Dec 15, 2020

Revert "Suggested edit to make clear what a quorum actually represent…

97dc4b7

…s. (#252)" (#610) This reverts commit 4eabf79. This notion of different quorums for doc read vs doc write is not true.

Uh oh!

Conversation

oliverdain commented Feb 27, 2018

Overview

Uh oh!

flimzy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oliverdain commented Mar 1, 2018

Uh oh!

oliverdain commented Mar 5, 2018

Uh oh!

flimzy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oliverdain commented Mar 5, 2018

Uh oh!

flimzy commented Mar 5, 2018

Uh oh!

oliverdain commented Mar 5, 2018

Uh oh!

oliverdain commented Mar 15, 2018

Uh oh!

wohali commented Mar 15, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants