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