Mercurial > evolve
changeset 363:5280e7ce026d stable
doc: big update of terms and summary of the concept
This is intended to be sent to the mailing list for discussion.
| author | Pierre-Yves.David@ens-lyon.org |
|---|---|
| date | Sun, 15 Jul 2012 12:49:25 +0200 |
| parents | 88cee22c89f1 |
| children | 616305c63510 |
| files | docs/glossary.rst docs/index.rst docs/obs-terms.rst |
| diffstat | 3 files changed, 254 insertions(+), 49 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/glossary.rst Sat Jul 14 18:10:24 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,41 +0,0 @@ ------------------------------------------------------ -Vocabulary ------------------------------------------------------ - -.. note:: all terminology is subject to change - -:obsolete marker: - express a relation from 0..n new changesets to 1 old changeset -:obsolete changesets: - non public changeset which is marked by an obsolete marker - -:unstable changeset: - changeset not obsolete but with obsolete ancestor - -:extinct changeset: - obsolete changeset without unstable descendant - -:suspended changeset: - obsolete changeset with unstable descendant - -:obsolete-parents: - previous versions of a changeset, through a direct obsolete marker. - -:obsolete-children: - new versions of a changeset, through a direct obsolete marker. - -:obsolete-ancestors: - previous versions of a changeset, through any number of obsolete marker - -:obsolete-descendant: - new versions of a changeset, through any number of obsolete marker - -:obsolete-diff: - diff between a changeset and its obsolete parent - -:obsolete-tip: - obsolete-descendants which are not obsolete themselves. - -:conflicting changeset: - multiple obsolete-tip for an obsolete changeset through diverging obsolete - markers (no changeset split marker)
--- a/docs/index.rst Sat Jul 14 18:10:24 2012 +0200 +++ b/docs/index.rst Sun Jul 15 12:49:25 2012 +0200 @@ -126,6 +126,7 @@ :maxdepth: 1 obs-concept + obs-terms obs-implementation obs-road-map @@ -186,11 +187,3 @@ you to manually specify target all the time. * trying to exchange obsolete relations with a static http repo will crash. - -Annexe -====== - -.. toctree:: - :maxdepth: 1 - - glossary
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/obs-terms.rst Sun Jul 15 12:49:25 2012 +0200 @@ -0,0 +1,253 @@ +----------------------------------------------------------- +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.