Commits

Anonymous committed 5280e7c

doc: big update of terms and summary of the concept

This is intended to be sent to the mailing list for discussion.

Comments (0)

Files changed (3)

docs/glossary.rst

------------------------------------------------------
-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)
    :maxdepth: 1
 
    obs-concept
+   obs-terms
    obs-implementation
    obs-road-map
 
   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
+-----------------------------------------------------------
+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.