Mercurial > evolve
diff docs/obs-terms.rst @ 368:c2f3cdd5a2a2 stable
[docs] obsolete: fix some typos
| author | Alain Leufroy <alain.leufroy@logilab.fr> |
|---|---|
| date | Sun, 15 Jul 2012 16:19:02 +0200 |
| parents | 5280e7ce026d |
| children | f348088d3b3f |
line wrap: on
line diff
--- a/docs/obs-terms.rst Sun Jul 15 14:42:21 2012 +0200 +++ b/docs/obs-terms.rst Sun Jul 15 16:19:02 2012 +0200 @@ -2,83 +2,83 @@ Terminology of the obsolete concept ----------------------------------------------------------- -Obsolete marker them self +Obsolete markers --------------------------------- -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 +The mutable concept is based on **obsolete markers**. Creating an obsolete +marker registers a relation between an 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: +Old changesets are called **precursors** while their new versions are called +**successors**. A marker always registers a single *precursor* to: + +- no *successor*: the *precursor* is just discarded. +- one *successor*: the *precursor* has been rewritten +- multiple *successors*: the *precursor* has been splitted in multiple + changesets. -- 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: -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* -: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* +.. :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. +Chainning obsolete markers is allowed to rewrite a changeset that is already a +*successor*. This is a kind of *second order version control*. +To clarify ambiguous situtations one can use **direct precursors** or +**direct successors** to name changesets that are directly related. -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: +The set of all **bsolete markers* forms a direct acyclic graph the same way +standard *parents*/*children* relation does. In this graph we have: -:any precursors: of a `A` are transitive precursors of `A`. (*direct - precursors* of `A` and *precursors* of *precursors*) +:any precursors: are transitive precursors of a changeset: *direct precursors* + and *precursors* of *precursors*. -:any successors: of a `A` are transitive successors of `A`. (*direct - successors* of `A` and *precursors* of *precursors*) +:any successors: are transitive successors of a changeset: *direct successors* + 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 +Obsolete markers may refer changesets that are not known locally. +So, *direct precursors* of a changeset may be unknown locally. +This is why we usually focus on the **first known precursors** of the rewritten +changeset. The same apply for *successors*. -(The same apply for successors) - -Item in *Any successors* which are not *obsolete* are called **newest -successors** +Changeset in *any successors* which are not **precursor**[#] 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. + better distinction between *direct successors* and **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. +The following table describes names and behaviors of changesets affected by +obsolete markers. Thge left column describes generic categories and the right +columns are about sub-categories. +---------------------+--------------------------+-----------------------------+ | **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. | +| Changeset in either | Obsolete changeset is | *extinct* changeset is | +| *draft* or *secret* | *mutable* used as a | *obsolete* which has only | +| phase. | *precursor*. | *obsolete* descendants. | | | | | -| | A changeset is used as | They can be safely: | -| | a precursors when at | | +| | A changeset is used as | They can safely be: | +| | a *precursor* 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. | +| | marker refers to it. | - silently excluded from | +| | | pull and push operations | +| | | - mostly ignored | +| | | - garbage collected | | | | | | | +-----------------------------+ | | | | | | | **suspended** | | | | | -| | | Suspended changesets are | -| | | obsolete one with at least | +| | | *suspended* changeset is | +| | | *obsolete* with at least | | | | one non-obsolete descendant | | | | | | | | Thoses descendants prevent | @@ -91,54 +91,52 @@ | | | | | | **troublesome** | **unstable** | | | | | -| | Troublesome commit have | Unstable changesets are | -| | unresolved issue caused | changesets with obsolete | -| | by obsolete relations. | ancestors. | +| | *troublesome* has | *unstable* is a changeset | +| | unresolved issue caused | with obsolete ancestors. | +| | by *obsolete* relations. | | | | | | -| | 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 | | +| | Possible issues are | It must be rebased on a | +| | listed in the next | non *troublesome* base to | +| | column. It is possible | solve the problem. | +| | for *troublesome* | | | | changeset to combine | (possible alternative name: | | | multiple issue at once. | precarious) | -| | (eg: conflicting and | | +| | (a.k.a. conflicting and | | | | unstable) +-----------------------------+ | | | | | | (possible alternative | **latecomer** | -| | name: unsettled, | | -| | troubled) | Latecomer changesets are | -| | | changesets that try to | -| | | be successors of public | -| | | changesets. | +| | names: unsettled, | | +| | troubled) | *latecomer* is a changeset | +| | | that tries to be successor | +| | | of public changesets. | | | | | | | | Public changeset can't | -| | | be obsolete. Latecomer | -| | | changeset need to be | -| | | rewritten as an overlay | -| | | to this public changeset. | +| | | be *precursor*. *latecomer* | +| | | need to be converted into | +| | | an overlay to this public | +| | | changeset. | | | | | -| | | (possible alternative names | +| | | (possible alternative names:| | | | mislead, naive, unaware, | | | | mindless, disenchanting) | | | | | | | +-----------------------------+ | | | **conflicting** | | | | | -| | | Conflicting changesets | -| | | happen when multiple | +| | | *conflicting* is changeset | +| | | that appears when multiple | | | | changesets are successors | -| | | of the same obsolete | -| | | changeset. | +| | | of the same precursor. | | | | | -| | | Conflicting changesets are | -| | | resolve through a three | -| | | ways merging between the | -| | | two conflicting changesets, | +| | | *conflicting* are solved | +| | | through a three ways merge | +| | | between the two | +| | | *conflictings*, | | | | using the last "obsolete- | | | | -common-ancestor" as the | | | | base. | | | | | -| | | (Changeset splitting is | +| | | (*splitting* is | | | | properly not detected as a | | | | conflict) | | | | | @@ -163,14 +161,13 @@ | 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) | +| no effect on the precussors 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. | +| When a *mutable* changeset becomes *immutable* (changing its phase from draft| +| to public) it 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. | +| The phase properties says that public changesets stay as *immutable* forever.| | | +------------------------------------------------------------------------------+ @@ -190,60 +187,58 @@ Existing terms `````````````` -Mercurial already use the following terms: +Mercurial already uses the following terms: -:amend: rewrite a changeset -:graft: copy a changeset -:rebase: move a changeset +:amend: to rewrite a changeset +:graft: to copy a changeset +:rebase: to move a changeset Uncommit ````````````` -remove files from a commit (and leave them as dirty in the working directory) +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 +The *evolve* extension have an `uncommit` command that aims to replace most `rollback` usage. Fold `````````` -Collapse multiple changeset into one +Collapse multiple changesets into a uniq one. -The evolve extensions *will* have a `fold` commands +The *evolve* extension will have a `fold` command. Prune `````````` Make a changeset obsolete without successors. -This an important operation as it should replace strip in 95% of the case. +This an important operation as it should mostly replace *strip*. -alternative name: +Alternative names: -- kill: nice name for effect when you forget the "hg" in front on "hg kill". -- obsolete: too vague, long and generic. +- kill: shall has funny effects when you forget "hg" in front of ``hg kill``. +- obsolete: too vague, too long and too generic. Stabilize ``````````````` -Automatically resolve troublesome changesets -(unstable, latecomer and conflicting) +Automatically resolve *troublesome* changesets +(*unstable*, *latecomer* and *conflicting*) -This is an important name as hg pull/pussh will suggest it the same way it +This is an important name as hg pull/push will suggest it the same way it suggest merging when you add heads. I do not like stabilize much. -alternative name: +alternative names: - solve (too generic ?) - evolve (too vague) - - .. note:: I'm not very happy with the naming of: - "ok" changeset