[02/11] couchdb commit: updated refs/heads/1824-replication-protocol to b41a7e4

[kx...@apache.org]

Group preface sections, fix definitions


Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/12a066ce
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/12a066ce
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/12a066ce

Branch: refs/heads/1824-replication-protocol
Commit: 12a066cece17c7b7bbd6790aa023def2bc04e4f6
Parents: 2f42657
Author: Alexander Shorin <kx...@apache.org>
Authored: Fri May 9 17:13:54 2014 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri May 9 17:13:54 2014 +0400

----------------------------------------------------------------------
 share/doc/src/replication/protocol.rst | 38 +++++++++++++++--------------
 1 file changed, 20 insertions(+), 18 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb/blob/12a066ce/share/doc/src/replication/protocol.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/protocol.rst b/share/doc/src/replication/protocol.rst
index 44426cd..574c84d 100644
--- a/share/doc/src/replication/protocol.rst
+++ b/share/doc/src/replication/protocol.rst
@@ -23,8 +23,11 @@ documents between 2 peers over HTTP/1.1 by using the public :ref:`CouchDB REST
 API <api>` and is based on the Apache CouchDB MVCC_ Data model.
 
 
+Preface
+=======
+
 Language
-========
+--------
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
@@ -32,21 +35,18 @@ document are to be interpreted as described in :rfc:`2119`.
 
 
 Goals
-=====
+-----
 
 The primary goal of this specification is to describe the `CouchDB Replication
-Protocol`.
-
-The secondary goal is to provide detailed enough information about the protocol
-to make it easy to build tools that can synchronize data with CouchDB.
+Protocol` under the hood.
 
-In theory the `CouchDB Replication Protocol` can be used between all products
-that implement it. However, the reference implementation, written in Erlang_,
-is provided by the couch_replicator_ module in Apache CouchDB.
+The secondary goal is to provide enough detailed information about the protocol
+to make it easy to build tools on any language and platform that can synchronize
+data with CouchDB.
 
 
 Definitions
-===========
+-----------
 
 JSON:
     :abbr:`JSON (JavaScript Object Notation)` is a text format for the
@@ -70,7 +70,9 @@ Leaf Revision:
     multiple Leaf Revisions (aka Conflict Revisions) due to concurrent updates.
 
 Document:
-    A document is a JSON object with a unique ID and Revision.
+    A document is a JSON object with an ID and Revision defined in ``_id`` and
+    ``_rev`` fields respectively. Document's ID MUST be unique across
+    the Database where it stored.
 
 Database:
     A collection of Documents with a unique URI.
@@ -79,7 +81,7 @@ Changes Feed:
     A stream of Document-changing events (create, update, delete) for
     the specified Database.
 
-Sequence:
+Sequence ID:
     An ID provided by the Changes Feed. It MUST be incremental,
     but SHOULD NOT be always an integer.
 
@@ -89,12 +91,12 @@ Source:
 Target:
     Database where the Documents are replicated to.
 
-Checkpoint:
-    Last processed Sequence ID.
-
 Replication:
     The one-way directed synchronization process of Source and Target endpoints.
 
+Checkpoint:
+    Intermediate Recorded Sequence ID that used for Replication recovery.
+
 Replicator:
     A service or an application which initiates and runs Replication.
 
@@ -121,11 +123,11 @@ Pull Replication:
 Continuous Replication:
     Replication that "never stops": after processing all events from
     Changes Feed, Replicator doesn't close the connection, but awaits new change
-    events from the Source. The connection is kept alive by periodical
-    heartbeats.
+    events from the Source. The connection keeps alive by periodical heartbeats.
 
 Replication Log:
-    A special Document that holds Replication history between Source and Target.
+    A special Document that holds Replication history (recorded Checkpoints
+    and few more statistics) between Source and Target.
 
 Replication ID:
     A unique value that unambiguously identifies the Replication Log.