diff mercurial/helptext/evolution.txt @ 47017:da4e6d7a8fdd

help: add topic about evolution, based on text from evolve extension

I've taken the text produced by `hg help evolution` when the evolve
extension is enabled and made that available by the same command with
just hg core. Changes I've made:

 * Added "(EXPERIMENTAL)" to the title. (That doesn't hide the topic
   from `hg help`, though.)

 * Replaced old-style `experimental.evolution=<names>` config by
   new-style `experimental.evolution.<name>=true`.

 * Replaces a "obsolete markers" by "obsolescence markers".

 * Removed most content from "Current feature status".

When the evolve extension is enabled, its help text takes precedence.

Differential Revision: https://phab.mercurial-scm.org/D10516

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/helptext/evolution.txt	Tue Apr 27 14:59:45 2021 -0700
@@ -0,0 +1,56 @@
+Obsolescence markers make it possible to mark changesets that have been
+deleted or superseded in a new version of the changeset.
+
+Unlike the previous way of handling such changes, by stripping the old
+changesets from the repository, obsolescence markers can be propagated
+between repositories. This allows for a safe and simple way of exchanging
+mutable history and altering it after the fact. Changeset phases are
+respected, such that only draft and secret changesets can be altered (see
+:hg:`help phases` for details).
+
+Obsolescence is tracked using "obsolescence markers", a piece of metadata
+tracking which changesets have been made obsolete, potential successors for
+a given changeset, the moment the changeset was marked as obsolete, and the
+user who performed the rewriting operation. The markers are stored
+separately from standard changeset data can be exchanged without any of the
+precursor changesets, preventing unnecessary exchange of obsolescence data.
+
+The complete set of obsolescence markers describes a history of changeset
+modifications that is orthogonal to the repository history of file
+modifications. This changeset history allows for detection and automatic
+resolution of edge cases arising from multiple users rewriting the same part
+of history concurrently.
+
+Current feature status
+======================
+
+This feature is still in development.
+
+Instability
+===========
+
+Rewriting changesets might introduce instability.
+
+There are two main kinds of instability: orphaning and diverging.
+
+Orphans are changesets left behind when their ancestors are rewritten.
+Divergence has two variants:
+
+* Content-divergence occurs when independent rewrites of the same changesets
+  lead to different results.
+
+* Phase-divergence occurs when the old (obsolete) version of a changeset
+  becomes public.
+
+It is possible to prevent local creation of orphans by using the following config::
+
+    [experimental]
+    evolution.createmarkers = true
+    evolution.exchange = true
+
+You can also enable that option explicitly::
+
+    [experimental]
+    evolution.createmarkers = true
+    evolution.exchange = true
+    evolution.allowunstable = true