--- 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

--- 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