--- 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