doc: big update of terms and summary of the concept
This is intended to be sent to the mailing list for discussion.
-----------------------------------------------------------
Terminology of the obsolete concept
-----------------------------------------------------------
Obsolete marker them self
---------------------------------
The mutable concept is based on the creation of **obsolete marker**. An obsolete
marker register a relation between the old obsoleted changeset and its newer
version.
The old changesets is called **precursors**. Its newer version are called
*successors*. A marker always register a single *precursors* but can refer
to:
- No *successors* at all if the *precursors* if just discarded.
- One *successor* at all if the *precursors* have been rewritten
- Multiple *successors* if the *precursors* have been splitted in myltiple
changeset.
The **precursors** and **successors** terms can be used on changeset directy:
:precursors: of a changeset `A` are changesets used as *precursors* by
obsolete marker using changeset `A` as *successors*
:successors: of a changeset `B` are changesets used as *successors* by
obsolete marker using changeset `B` as *precursors*
*Precursors* and *successors* directly related within the same marker are called
**direct precursors** and **direct successors** in ambiguous situation.
The set of all *obsolete markers* create a direct acyclic graph the same way
standard *parent* and *children* relation do. In this graph we have:
:any precursors: of a `A` are transitive precursors of `A`. (*direct
precursors* of `A` and *precursors* of *precursors*)
:any successors: of a `A` are transitive successors of `A`. (*direct
successors* of `A` and *precursors* of *precursors*)
Obsolete markers may revert to changesets that are not known locally. *Direct
precursors* of a changeset may be unknown locally. This is why we usually focus
on the **first known precursors** of changeset
(The same apply for successors)
Item in *Any successors* which are not *obsolete* are called **newest
successors**
.. note:: I'm not very happy with this naming scheme and I'm looking for a
better distinction between direct-successors, any-successors.
Possible changesets "type"
---------------------------------
The following table describe name and behavior of changesets affected by
obsolete marker. Left column describe generic category and right column are
about sub-category.
+---------------------+--------------------------+-----------------------------+
| **mutable** | **obsolete** | **extinct** |
| | | |
| Changeset in either | Obsolete changesets are | Extinct changesets are |
| *draft* or *secret* | mutable changeset used | obsolete one with obsolete |
| phases. | as a precursors. | only descendants. |
| | | |
| | A changeset is used as | They can be safely: |
| | a precursors when at | |
| | least one obsolete | - hidden in the UI, |
| | refer to it in the | - silently excluded from pp |
| | precursors field. | pull and push,t operation |
| | | - ignored by most operation |
| | | - garbage collected. |
| | | |
| | +-----------------------------+
| | | |
| | | **suspended** |
| | | |
| | | Suspended changesets are |
| | | obsolete one with at least |
| | | one non-obsolete descendant |
| | | |
| | | Thoses descendants prevent |
| | | properties of extincts |
| | | changesets to apply. But |
| | | they will refuse to be |
| | | pushed without --force. |
| | | |
| +--------------------------+-----------------------------+
| | | |
| | **troublesome** | **unstable** |
| | | |
| | Troublesome commit have | Unstable changesets are |
| | unresolved issue caused | changesets with obsolete |
| | by obsolete relations. | ancestors. |
| | | |
| | Possible issues are | They must be rebased on a |
| | listed in the next | better base to solve the |
| | column. It is possible | situation. |
| | for troublesome | |
| | changeset to combine | (possible alternative name: |
| | multiple issue at once. | precarious) |
| | (eg: conflicting and | |
| | unstable) +-----------------------------+
| | | |
| | (possible alternative | **latecomer** |
| | name: unsettled, | |
| | troubled) | Latecomer changesets are |
| | | changesets that try to |
| | | be successors of public |
| | | changesets. |
| | | |
| | | Public changeset can't |
| | | be obsolete. Latecomer |
| | | changeset need to be |
| | | rewritten as an overlay |
| | | to this public changeset. |
| | | |
| | | (possible alternative names |
| | | mislead, naive, unaware, |
| | | mindless, disenchanting) |
| | | |
| | +-----------------------------+
| | | **conflicting** |
| | | |
| | | Conflicting changesets |
| | | happen when multiple |
| | | changesets are successors |
| | | of the same obsolete |
| | | changeset. |
| | | |
| | | Conflicting changesets are |
| | | resolve through a three |
| | | ways merging between the |
| | | two conflicting changesets, |
| | | using the last "obsolete- |
| | | -common-ancestor" as the |
| | | base. |
| | | |
| | | (Changeset splitting is |
| | | properly not detected as a |
| | | conflict) |
| | | |
| +--------------------------+-----------------------------+
| | |
| | Mutable changesets which are neither *obsolete* or |
| | *troublesome* are *"ok"*. |
| | |
| | Do we really need a name for it ? *"ok"* is a pretty |
| | crappy name :-/ other possibilities are: |
| | |
| | - stable (confusing with stable branch) |
| | - sane |
| | - healthy |
| | |
+---------------------+--------------------------------------------------------+
| |
| **immutable** |
| |
| Changesets in the *public* phases. |
| |
| Rewriting operation refuse to work on immutable changeset. |
| |
| Obsolete markers that refer an immutable changeset as precursors have |
| no effect on the precussors changeset (but may have effect on the |
| successors) |
| |
| When a mutable changeset becomes immutable its is just *immutable* and loose |
| any property of it's former state. |
| |
| By phase property, once a changeset becomes a public immutable changeset, |
| you can expect it to remain as such forever. |
| |
+------------------------------------------------------------------------------+
.. note:: I'm not very happy with the naming of:
- "ok" changeset
- latecomer
- troublesome
Any better idea are welcome.
Command and operation name
---------------------------------
Existing terms
``````````````
Mercurial already use the following terms:
:amend: rewrite a changeset
:graft: copy a changeset
:rebase: move a changeset
Uncommit
`````````````
remove files from a commit (and leave them as dirty in the working directory)
The evolve extension have an `uncommit` command that aims to replace most
`rollback` usage.
Fold
``````````
Collapse multiple changeset into one
The evolve extensions *will* have a `fold` commands
Prune
``````````
Make a changeset obsolete without successors.
This an important operation as it should replace strip in 95% of the case.
alternative name:
- kill: nice name for effect when you forget the "hg" in front on "hg kill".
- obsolete: too vague, long and generic.
Stabilize
```````````````
Automatically resolve troublesome changesets
(unstable, latecomer and conflicting)
This is an important name as hg pull/pussh will suggest it the same way it
suggest merging when you add heads.
I do not like stabilize much.
alternative name:
- solve (too generic ?)
- evolve (too vague)
.. note:: I'm not very happy with the naming of:
- "ok" changeset
- latecomer
- troublesome
Any better idea are welcome.