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

login
register
mail settings
Submitter phabricator
Date April 28, 2021, 3:08 p.m.
Message ID <differential-rev-PHID-DREV-56nlv6mhgrwqcgeijzh6-req@mercurial-scm.org>
Download mbox | patch
Permalink /patch/48836/
State Superseded
Headers show

Comments

phabricator - April 28, 2021, 3:08 p.m.
martinvonz created this revision.
Herald added a reviewer: hg-reviewers.
Herald added a subscriber: mercurial-patches.
pulkit accepted this revision.
This revision is now accepted and ready to land.

REVISION SUMMARY
  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.

REPOSITORY
  rHG Mercurial

BRANCH
  default

REVISION DETAIL
  https://phab.mercurial-scm.org/D10516

AFFECTED FILES
  mercurial/help.py
  mercurial/helptext/evolution.txt
  tests/test-globalopts.t
  tests/test-help-hide.t
  tests/test-help.t
  tests/test-hgweb-json.t

CHANGE DETAILS




To: martinvonz, #hg-reviewers
Cc: mercurial-patches, mercurial-devel

Patch

diff --git a/tests/test-hgweb-json.t b/tests/test-hgweb-json.t
--- a/tests/test-hgweb-json.t
+++ b/tests/test-hgweb-json.t
@@ -2272,6 +2272,10 @@ 
         "topic": "environment"
       },
       {
+        "summary": "Safely rewriting history (EXPERIMENTAL)",
+        "topic": "evolution"
+      },
+      {
         "summary": "Using Additional Features",
         "topic": "extensions"
       },
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -169,6 +169,7 @@ 
   Concepts:
   
    bundlespec    Bundle File Formats
+   evolution     Safely rewriting history (EXPERIMENTAL)
    glossary      Glossary
    phases        Working with Phases
    subrepos      Subrepositories
@@ -298,6 +299,7 @@ 
   Concepts:
   
    bundlespec    Bundle File Formats
+   evolution     Safely rewriting history (EXPERIMENTAL)
    glossary      Glossary
    phases        Working with Phases
    subrepos      Subrepositories
@@ -2274,6 +2276,13 @@ 
   Environment Variables
   </td></tr>
   <tr><td>
+  <a href="/help/evolution">
+  evolution
+  </a>
+  </td><td>
+  Safely rewriting history (EXPERIMENTAL)
+  </td></tr>
+  <tr><td>
   <a href="/help/extensions">
   extensions
   </a>
diff --git a/tests/test-help-hide.t b/tests/test-help-hide.t
--- a/tests/test-help-hide.t
+++ b/tests/test-help-hide.t
@@ -117,6 +117,7 @@ 
   Concepts:
   
    bundlespec    Bundle File Formats
+   evolution     Safely rewriting history (EXPERIMENTAL)
    glossary      Glossary
    phases        Working with Phases
    subrepos      Subrepositories
@@ -254,6 +255,7 @@ 
   Concepts:
   
    bundlespec    Bundle File Formats
+   evolution     Safely rewriting history (EXPERIMENTAL)
    glossary      Glossary
    phases        Working with Phases
    subrepos      Subrepositories
diff --git a/tests/test-globalopts.t b/tests/test-globalopts.t
--- a/tests/test-globalopts.t
+++ b/tests/test-globalopts.t
@@ -419,6 +419,7 @@ 
   Concepts:
   
    bundlespec    Bundle File Formats
+   evolution     Safely rewriting history (EXPERIMENTAL)
    glossary      Glossary
    phases        Working with Phases
    subrepos      Subrepositories
@@ -552,6 +553,7 @@ 
   Concepts:
   
    bundlespec    Bundle File Formats
+   evolution     Safely rewriting history (EXPERIMENTAL)
    glossary      Glossary
    phases        Working with Phases
    subrepos      Subrepositories
diff --git a/mercurial/helptext/evolution.txt b/mercurial/helptext/evolution.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/helptext/evolution.txt
@@ -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
diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -540,6 +540,12 @@ 
             TOPIC_CATEGORY_CONCEPTS,
         ),
         (
+            [b"evolution"],
+            _(b"Safely rewriting history (EXPERIMENTAL)"),
+            loaddoc(b'evolution'),
+            TOPIC_CATEGORY_CONCEPTS,
+        ),
+        (
             [b'scripting'],
             _(b'Using Mercurial from scripts and automation'),
             loaddoc(b'scripting'),