doc: big update of terms and summary of the concept
This is intended to be sent to the mailing list for discussion.
--- 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.