[PATCH evolve-ext] help: try to document evolution states

[timeless]

# HG changeset patch
# User timeless at gmail.com
# Date 1464206788 0
#      Wed May 25 20:06:28 2016 +0000
# Node ID 103207c902f828fc06b594ffac60a5172faaed2f
# Parent  a4de197218cf11de51b2a73c774be6ebaeba337a
# Available At https://bitbucket.org/timeless/mutable-history/
#              hg pull https://bitbucket.org/timeless/mutable-history/ -r 103207c902f8
help: try to document evolution states

diff -r a4de197218cf -r 103207c902f8 hgext/evolve.py
--- a/hgext/evolve.py	Fri May 27 17:36:07 2016 +0200
+++ b/hgext/evolve.py	Wed May 25 20:06:28 2016 +0000
@@ -48,6 +48,62 @@
 resolution of edge cases arising from multiple users rewriting the same part
 of history concurrently.
 
+obsolete vs non-obsolete
+========================
+
+normal:
+  Commits without replacements and that have not been pruned, and for which all
+  ancestors are also normal.
+
+  Rendered in :hg:`log -G`: default (typically: `o`, can be `@` if active).
+
+obsolete:
+  Changesets for which markers indicate they should no longer be used.
+  There may be replacements (successors), or there may not (if it has been
+  pruned).
+  If there are descendants that are not obsolete, the changeset is reported as
+  "suspended", otherwise it will only show up if you use `--hidden` or if
+  something like a bookmark or the current checkout is pointing to it.
+
+  Rendered in :hg:`log -G`: `x`.
+
+non-obsolete:
+  A changeset which isn't obsolete may still have problems related to obsolete
+  changesets. Such a changeset is said to be "troubled".
+
+Obsolete
+--------
+
+superseded:
+  Replacement changesets have been recorded.
+
+pruned:
+  Changeset has been marked for removal without a replacement.
+
+extinct:
+  Obsolete changesets of which all descendants are also obsolete.
+
+  (This label will probably be removed.)
+
+suspended:
+  Obsolete changesets with non-obsolete descendants.
+
+Troubled changesets
+===================
+
+It's possible for a changeset to have multiple problems.
+Each of the following could apply to an individual changeset.
+
+unstable:
+  Non-obsolete changesets with obsolete ancestors.
+
+bumped:
+  Mutable changesets marked as successors of public changesets.
+
+divergent:
+  Final successors of changesets for which multiple such final successors of a
+  changeset exist.
+
 Current feature status
 ======================
 
diff -r a4de197218cf -r 103207c902f8 tests/test-evolve.t
--- a/tests/test-evolve.t	Fri May 27 17:36:07 2016 +0200
+++ b/tests/test-evolve.t	Wed May 25 20:06:28 2016 +0000
@@ -72,6 +72,62 @@
       resolution of edge cases arising from multiple users rewriting the same
       part of history concurrently.
   
+      obsolete vs non-obsolete
+      ========================
+  
+      normal:
+        Commits without replacements and that have not been pruned, and for
+        which all ancestors are also normal.
+  
+        Rendered in 'hg log -G': default (typically: 'o', can be '@' if active).
+  
+      obsolete:
+        Changesets for which markers indicate they should no longer be used.
+        There may be replacements (successors), or there may not (if it has been
+        pruned). If there are descendants that are not obsolete, the changeset
+        is reported as "suspended", otherwise it will only show up if you use '
+        --hidden' or if something like a bookmark or the current checkout is
+        pointing to it.
+  
+        Rendered in 'hg log -G': 'x'.
+  
+      non-obsolete:
+        A changeset which isn't obsolete may still have problems related to
+        obsolete changesets. Such a changeset is said to be "troubled".
+  
+      Obsolete
+      --------
+  
+      superseded:
+        Replacement changesets have been recorded.
+  
+      pruned:
+        Changeset has been marked for removal without a replacement.
+  
+      extinct:
+        Obsolete changesets of which all descendants are also obsolete.
+  
+        (This label will probably be removed.)
+  
+      suspended:
+        Obsolete changesets with non-obsolete descendants.
+  
+      Troubled changesets
+      ===================
+  
+      It's possible for a changeset to have multiple problems. Each of the
+      following could apply to an individual changeset.
+  
+      unstable:
+        Non-obsolete changesets with obsolete ancestors.
+  
+      bumped:
+        Mutable changesets marked as successors of public changesets.
+  
+      divergent:
+        Final successors of changesets for which multiple such final successors
+        of a changeset exist.
+  
       Current feature status
       ======================