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