--- a/CHANGELOG	Tue Aug 21 04:08:38 2018 +0200
+++ b/CHANGELOG	Tue Aug 21 14:23:47 2018 +0200
@@ -4,12 +4,13 @@
 8.1.1 - in progress
 -------------------
 
+  * clone: fix possible crash when using clone bundle and forcing cache warming
   * evolve: properly set second parent during conflict (issue5927)
+  * next: delete the evolvestate after aborting interrupted `next --evolve`
   * next: fix topic restriction when passing --evolve
-  * clone: fix possible crash when using clone bundle and forcing cache warming
   * obshashrange: fix speed and consistency issues during cache invalidation
   * obshashrange: properly persist all caches involved in obshashrange discovery
-  * delete the evolvestate after aborting interrupted `next --evolve`
+  * prune: improve documentation
 
 8.1.0 -- 2018-08-03
 -------------------

--- a/hgext3rd/evolve/cmdrewrite.py	Tue Aug 21 04:08:38 2018 +0200
+++ b/hgext3rd/evolve/cmdrewrite.py	Tue Aug 21 14:23:47 2018 +0200
@@ -952,28 +952,29 @@
     _('[OPTION] [-r] REV...'))
 # XXX -U  --noupdate option to prevent wc update and or bookmarks update ?
 def cmdprune(ui, repo, *revs, **opts):
-    """hide changesets by marking them obsolete
+    """mark changesets as obsolete or succeeded by another changeset
 
-    Pruned changesets are obsolete with no successors. If they also have no
-    descendants, they are hidden (invisible to all commands).
-
-    Non-obsolete descendants of pruned changesets become "unstable". Use :hg:`evolve`
-    to handle this situation.
+    Pruning changesets marks them obsolete, hiding them from the
+    history log, provided they have no descendants. Otherwise, all
+    such descendants that aren't themselves obsolete become
+    "unstable". Use :hg:`evolve` to handle this situation.
 
     When you prune the parent of your working copy, Mercurial updates the working
     copy to a non-obsolete parent.
 
-    You can use ``--succ`` to tell Mercurial that a newer version (successor) of the
+    You can use ``-s/--succ`` to tell Mercurial that a newer version (successor) of the
     pruned changeset exists. Mercurial records successor revisions in obsolescence
     markers.
 
-    You can use the ``--biject`` option to specify a 1-1 mapping (bijection) between
-    revisions to pruned (precursor) and successor changesets. This option may be
-    removed in a future release (with the functionality provided automatically).
+    If you prune a single revision and specify multiple revisions in
+    ``-s/--succ``, you are recording a "split" and must acknowledge it by
+    passing ``--split``. Similarly, when you prune multiple changesets with a
+    single successor, you must pass the ``--fold`` option.
 
-    If you specify multiple revisions in ``--succ``, you are recording a "split" and
-    must acknowledge it by passing ``--split``. Similarly, when you prune multiple
-    changesets with a single successor, you must pass the ``--fold`` option.
+    If you want to supersede multiple revisions at the same time, use
+    ``--biject`` option to pair the pruned precursor and successor changesets.
+    This is commonly useful for resolving history divergence, or when someone
+    else does edits history without obsolescence enabled.
     """
     _checknotesize(ui, opts)
     revs = scmutil.revrange(repo, list(revs) + opts.get('rev'))