Mercurial > evolve
view docs/obs-terms.rst @ 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 | |
| children | c2f3cdd5a2a2 |
line wrap: on
line source
----------------------------------------------------------- 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.