( )⚙ D10516 help: add topic about evolution, based on text from evolve extension

This is an archive of the discontinued Mercurial Phabricator instance.

Differential D10516

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

Authored by martinvonz on Apr 27 2021, 6:53 PM.

Details

Reviewers
pulkit
Group Reviewers
hg-reviewers
Commits
rHGda4e6d7a8fdd: help: add topic about evolution, based on text from evolve extension
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.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Revision Contents
Changeset List

Diff 27246

mercurial/help.py

), ),
( (
[b"phases"], [b"phases"],
_(b"Working with Phases"), _(b"Working with Phases"),
loaddoc(b'phases'), loaddoc(b'phases'),
TOPIC_CATEGORY_CONCEPTS, TOPIC_CATEGORY_CONCEPTS,
), ),
( (
[b"evolution"],
_(b"Safely rewriting history (EXPERIMENTAL)"),
loaddoc(b'evolution'),
TOPIC_CATEGORY_CONCEPTS,
),
(
[b'scripting'], [b'scripting'],
_(b'Using Mercurial from scripts and automation'), _(b'Using Mercurial from scripts and automation'),
loaddoc(b'scripting'), loaddoc(b'scripting'),
TOPIC_CATEGORY_MISC, TOPIC_CATEGORY_MISC,
), ),
( (
[b'internals'], [b'internals'],
_(b"Technical implementation topics"), _(b"Technical implementation topics"),

mercurial/helptext/evolution.txt

  • This file was added.
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

tests/test-globalopts.t

flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
Miscellaneous: Miscellaneous:
deprecated Deprecated Features deprecated Deprecated Features
internals Technical implementation topics internals Technical implementation topics
flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
Miscellaneous: Miscellaneous:
deprecated Deprecated Features deprecated Deprecated Features
internals Technical implementation topics internals Technical implementation topics
scripting Using Mercurial from scripts and automation scripting Using Mercurial from scripts and automation
(use 'hg help -v' to show built-in aliases and global options) (use 'hg help -v' to show built-in aliases and global options)
#endif #endif
Not tested: --debugger Not tested: --debugger

tests/test-help-hide.t

flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
Miscellaneous: Miscellaneous:
deprecated Deprecated Features deprecated Deprecated Features
internals Technical implementation topics internals Technical implementation topics
flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
(use 'hg help -v' to show built-in aliases and global options) (use 'hg help -v' to show built-in aliases and global options)

tests/test-help.t

flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
Miscellaneous: Miscellaneous:
deprecated Deprecated Features deprecated Deprecated Features
internals Technical implementation topics internals Technical implementation topics
flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
Miscellaneous: Miscellaneous:
deprecated Deprecated Features deprecated Deprecated Features
internals Technical implementation topics internals Technical implementation topics
<tr><td> <tr><td>
<a href="/help/environment"> <a href="/help/environment">
environment environment
</a> </a>
</td><td> </td><td>
Environment Variables Environment Variables
</td></tr> </td></tr>
<tr><td> <tr><td>
<a href="/help/evolution">
evolution
</a>
</td><td>
Safely rewriting history (EXPERIMENTAL)
</td></tr>
<tr><td>
<a href="/help/extensions"> <a href="/help/extensions">
extensions extensions
</a> </a>
</td><td> </td><td>
Using Additional Features Using Additional Features
</td></tr> </td></tr>
<tr><td> <tr><td>
<a href="/help/filesets"> <a href="/help/filesets">

tests/test-hgweb-json.t

"summary": "Diff Formats", "summary": "Diff Formats",
"topic": "diffs" "topic": "diffs"
}, },
{ {
"summary": "Environment Variables", "summary": "Environment Variables",
"topic": "environment" "topic": "environment"
}, },
{ {
"summary": "Safely rewriting history (EXPERIMENTAL)",
"topic": "evolution"
},
{
"summary": "Using Additional Features", "summary": "Using Additional Features",
"topic": "extensions" "topic": "extensions"
}, },
{ {
"summary": "Specifying File Sets", "summary": "Specifying File Sets",
"topic": "filesets" "topic": "filesets"
}, },
{ {