# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@octobus.net>
# Date 1500832326 -7200
# Node ID 2bd0b0996cfb8452a4d7ce5f35247d2a294b39a1
# Parent  78b0c605313945685980a44da3e33b330711401d
evolve: document the various instability/troubles

We need something to point people at.

diff -r 78b0c6053139 -r 2bd0b0996cfb hgext3rd/evolve/__init__.py
--- a/hgext3rd/evolve/__init__.py	Sun Jul 23 19:37:29 2017 +0200
+++ b/hgext3rd/evolve/__init__.py	Sun Jul 23 19:52:06 2017 +0200
@@ -214,7 +214,41 @@
 
 Obsolescence markers will be exchanged between repositories that explicitly
 assert support for the obsolescence feature (this can currently only be done
-via an extension).""".strip()
+via an extension).
+
+Instability
+==========
+
+(note: the vocabulary is in the process of being updated)
+
+Rewriting changesets might introduce instability (currently 'trouble').
+
+There are two main kinds of instability: orphaning and diverging.
+
+Orphans are changesets left behind when their ancestors are rewritten, (currently: 'unstable').
+Divergence has two variants:
+
+* Content-divergence occurs when independent rewrites of the same changesets
+  lead to different results. (currently: 'divergent')
+
+* Phase-divergence occurs when the old (obsolete) version of a changeset
+  becomes public. (currently: 'bumped')
+
+If it possible to prevent local creation of orphans by using the following config::
+
+    [experimental]
+    evolution=createmarkers,allnewcommands,exchange
+
+You can also enable that option explicitly::
+
+    [experimental]
+    evolution=createmarkers,allnewcommands,allowunstable,exchange
+
+or simply::
+
+    [experimental]
+    evolution=all
+""".strip()
 
 
 import os
diff -r 78b0c6053139 -r 2bd0b0996cfb tests/test-evolve.t
--- a/tests/test-evolve.t	Sun Jul 23 19:37:29 2017 +0200
+++ b/tests/test-evolve.t	Sun Jul 23 19:52:06 2017 +0200
@@ -80,6 +80,38 @@
       Obsolescence markers will be exchanged between repositories that
       explicitly assert support for the obsolescence feature (this can currently
       only be done via an extension).
+  
+      Instability ==========
+  
+      (note: the vocabulary is in the process of being updated)
+  
+      Rewriting changesets might introduce instability (currently 'trouble').
+  
+      There are two main kinds of instability: orphaning and diverging.
+  
+      Orphans are changesets left behind when their ancestors are rewritten,
+      (currently: 'unstable'). Divergence has two variants:
+  
+      * Content-divergence occurs when independent rewrites of the same
+        changesets lead to different results. (currently: 'divergent')
+      * Phase-divergence occurs when the old (obsolete) version of a changeset
+        becomes public. (currently: 'bumped')
+  
+      If it possible to prevent local creation of orphans by using the following
+      config:
+  
+        [experimental]
+        evolution=createmarkers,allnewcommands,exchange
+  
+      You can also enable that option explicitly:
+  
+        [experimental]
+        evolution=createmarkers,allnewcommands,allowunstable,exchange
+  
+      or simply:
+  
+        [experimental]
+        evolution=all
 
 various init