[GitHub] wohali commented on a change in pull request #123: Documentation for the scheduling replicator

[gi...@git.apache.org]

wohali commented on a change in pull request #123: Documentation for the scheduling replicator
URL: https://github.com/apache/couchdb-documentation/pull/123#discussion_r114005871
 
 

 ##########
 File path: src/replication/replicator.rst
 ##########
 @@ -155,98 +203,192 @@ the following order:
 .. code-block:: javascript
 
     {
-        "_id": "doc_A",
-        "source":  "http://myserver.com:5984/foo",
-        "target":  "http://user:pass@localhost:5984/bar"
+        "_id": "my_rep",
+        "source":  "http://user:pass@localhost:5984/foo",
+        "target":  "http://user:pass@localhost:5984/bar",
+        "create_target":  true,
+        "continuous": true
     }
 
 and
 
 .. code-block:: javascript
 
     {
-        "_id": "doc_B",
-        "source":  "http://myserver.com:5984/foo",
-        "target":  "http://user:pass@localhost:5984/bar"
-    }
-
-Both describe exactly the same replication (only their ``_ids`` differ). In this
-case document ``doc_A`` triggers the replication, getting updated by CouchDB
-with the fields ``_replication_state``, ``_replication_state_time`` and
-``_replication_id``, just like it was described before. Document ``doc_B``
-however, is only updated with one field, the ``_replication_id`` so it will
-look like this:
-
-.. code-block:: javascript
-
-    {
-        "_id": "doc_B",
-        "source":  "http://myserver.com:5984/foo",
+        "_id": "my_rep_dup",
+        "source":  "http://user:pass@localhost:5984/foo",
         "target":  "http://user:pass@localhost:5984/bar",
-        "_replication_id":  "c0ebe9256695ff083347cbf95f93e280"
+        "create_target":  true,
+        "continuous": true
     }
 
-While document ``doc_A`` will look like this:
-
-.. code-block:: javascript
-
-    {
-        "_id": "doc_A",
-        "source":  "http://myserver.com:5984/foo",
-        "target":  "http://user:pass@localhost:5984/bar",
-        "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
-        "_replication_state":  "triggered",
-        "_replication_state_time":  1297974122
-    }
+Both describe exactly the same replication (only their ``_ids``
+differ). In this case document ``my_rep`` triggers the
+replication. While ``my_rep_dup``` will fail. Inspecting
+``_scheduler/docs`` explains exactly why it failed:
+
+.. code-block:: json
+
+        {
+            "database": "_replicator",
+            "doc_id": "my_rep_dup",
+            "error_count": 1,
+            "id": null,
+            "info": "Replication `a81a78e822837e66df423d54279c15fe+continuous+create_target` specified by document `my_rep_dup` already started, triggered by document `my_rep` from db `_replicator`",
+            "last_updated": "2017-04-05T21:41:51Z",
+            "source": "http://adm:*****@localhost:5984/foo/",
+            "start_time": "2017-04-05T21:41:51Z",
+            "state": "failed",
+            "target": "http://adm:*****@localhost:5984/bar/"
+        }
 
-Note that both document get exactly the same value for the ``_replication_id``
-field. This way you can identify which documents refer to the same replication -
-you can for example define a view which maps replication IDs to document IDs.
+Notice the state for this replication is ``failed``. Unlike
+``crashing``, ``failed`` state is terminal. As long as both documents
+are present replicator will not retry to run this replication. Another
+reason for could be malformed documents. For example if worker process
+count is specified as a string (``"worker_processes": "a few"``)
+instead of an integer.
+
+Replication states
+==================
+
+Replication jobs during their life-cycle pass through various
+states. This is a diagram of all the states and transitions
+between them:
+
+.. figure:: ../../images/replication-state-diagram.svg
+     :align: center
+     :alt: Replication state diagram
+
+     Replication state diagram
+
+Green and red shapes represent replication job states.
+
+Yellow shapes represent external APIs, that's how users interact with
+the replicator. Writing documents to ``_replicator`` is the preferred
+way of creating replications, but posting to the ``_replicate`` HTTP
+endpoint is also supported.
+
+.. note:: Replications created through the ``_replicate`` endpoint
 
 Review comment:
   As we're talking about getting a 2.1.0 out the door, let's raise the priority on COUCHDB-3235 and get that fix in before we release.
 
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services