annotate docs/obs-terms.rst @ 4932:fff7ddbef685 stable

docs: correct node hashes in sharing.rst based on test-sharing.t

.. Copyright 2011 Pierre-Yves David <[e-mail]>
..                Logilab SA        <[e-mail]>

-----------------------------------
Terminology of the obsolete concept
-----------------------------------

Obsolete markers
----------------

The mutable concept is based on **obsolete markers**. Creating an obsolete
marker registers a relation between an old obsoleted changeset and its newer
version.

Old changesets are called **predecessors** while their new versions are called
**successors**. A marker always registers a single *predecessor* and:

- no *successor*: the *predecessor* is just discarded.
- one *successor*: the *predecessor* has been rewritten
- multiple *successors*: the *predecessor* were splits in multiple
  changesets.

.. The *predecessors* and *successors* terms can be used on changeset directly:

.. :predecessors: of a changeset `A` are changesets used as *predecessors* 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 *predecessors*

Chaining 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 situations one can use **direct predecessors** or
**direct successors** to name changesets that are directly related.

The set of all *obsolete markers* forms a direct acyclic graph the same way
standard *parents*/*children* relation does. In this graph we have:

:any predecessors: are transitive predecessors of a changeset: *direct predecessors*
                 and *predecessors* of *predecessors*.

:any successors: are transitive successors of a changeset: *direct successors*
                 and *successors*  of *successors*)

Obsolete markers may refer changesets that are not known locally.
So, *direct predecessors* of a changeset may be unknown locally.
This is why we usually focus on the **first known predecessors**  of the rewritten
changeset. The same apply for *successors*.

Changeset 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* and **any successors**.

Possible changesets "type"
--------------------------

The following table describes names and behaviors of changesets affected by
obsolete markers. The left column describes generic categories and the right
columns are about sub-categories.


+---------------------+--------------------------+-----------------------------+
| **mutable**         | **obsolete**             | **extinct**                 |
|                     |                          |                             |
| Changeset in either | Obsolete changeset is    | *extinct* changeset is      |
| *draft* or *secret* | *mutable* used as a      | *obsolete* which has only   |
| phase.              | *predecessor*.           | *obsolete* descendants.     |
|                     |                          |                             |
|                     | A changeset is used as   | They can safely be:         |
|                     | a *predecessor* when at  |                             |
|                     | least one obsolete       | - hidden in the UI,         |
|                     | marker refers to it      | - silently excluded from    |
|                     | as predecessors.         |   pull and push operations  |
|                     |                          | - mostly ignored            |
|                     |                          | - garbage collected         |
|                     |                          |                             |
|                     |                          +-----------------------------+
|                     |                          |                             |
|                     |                          | **suspended**               |
|                     |                          |                             |
|                     |                          | *suspended* changeset is    |
|                     |                          | *obsolete* with at least    |
|                     |                          | one non-obsolete descendant |
|                     |                          |                             |
|                     |                          | Those descendants prevent   |
|                     |                          | properties of extinct       |
|                     |                          | changesets to apply. But    |
|                     |                          | they will refuse to be      |
|                     |                          | pushed without --force.     |
|                     |                          |                             |
|                     +--------------------------+-----------------------------+
|                     |                          |                             |
|                     | **unstable**             | **orphan**                  |
|                     |                          |                             |
|                     | *unstable*    has        | *orphan* is a changeset     |
|                     | unresolved issue caused  | with obsolete ancestors.    |
|                     | by *obsolete* relations. |                             |
|                     |                          |                             |
|                     | Possible issues are      | It must be rebased on a     |
|                     | listed in the next       | non *unstable*    base to   |
|                     | column. It is possible   | solve the problem.          |
|                     | for *unstable*           |                             |
|                     | changeset to combine     | (possible alternative name: |
|                     | multiple issue at once.  | precarious)                 |
|                     | (a.k.a. content-divergent|                             |
|                     | and orphan)              +-----------------------------+
|                     |                          |                             |
|                     | (possible alternative    | **phase-divergent**         |
|                     | names: unsettled,        |                             |
|                     | troublesome              | *phase-divergent* is a      |
|                     |                          | changeset that tries to be  |
|                     |                          | successor of a public       |
|                     |                          | changeset.                  |
|                     |                          |                             |
|                     |                          | Public changeset can't      |
|                     |                          | be deleted and replace      |
|                     |                          | *phase-divergent*           |
|                     |                          | need to be converted into   |
|                     |                          | an overlay to this public   |
|                     |                          | changeset.                  |
|                     |                          |                             |
|                     |                          | (possible alternative names:|
|                     |                          | mislead, naive, unaware,    |
|                     |                          | mindless, disenchanting)    |
|                     |                          |                             |
|                     |                          +-----------------------------+
|                     |                          | **content-divergent**       |
|                     |                          |                             |
|                     |                          | *content-divergent*   is a  |
|                     |                          | changeset that appears when |
|                     |                          | multiple changesets are     |
|                     |                          | successors of the same      |
|                     |                          | predecessor.                |
|                     |                          |                             |
|                     |                          | *content-divergent*   are   |
|                     |                          | solved through a three way  |
|                     |                          | merge between the two       |
|                     |                          | *content-divergent*   ,     |
|                     |                          | using the last "obsolete-   |
|                     |                          | -common-ancestor" as the    |
|                     |                          | base.                       |
|                     |                          |                             |
|                     |                          | (*splitting* is             |
|                     |                          | properly not detected as a  |
|                     |                          | conflict)                   |
|                     |                          |                             |
|                     |                          | (possible alternative names:|
|                     |                          | clashing, rival, concurrent,|
|                     |                          | conflicting)                |
|                     |                          |                             |
|                     +--------------------------+-----------------------------+
|                     |                                                        |
|                     | Mutable changesets which are neither *obsolete* or     |
|                     | *unstable*    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 predecessors have      |
| no effect on the predecessors but may have effect on the successors.         |
|                                                                              |
| 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.                                                                       |
|                                                                              |
| The phase properties says that public changesets stay as *immutable* forever.|
|                                                                              |
+------------------------------------------------------------------------------+



Command and operation name
--------------------------


Existing terms
``````````````

Mercurial core already uses the following terms:

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

The *evolve* extension have an `uncommit` command that aims to replace most
`rollback` usage.

Fold
````

Collapse multiple changesets into a unique one.

The *evolve* extension will have a `fold` command.

Prune
`````

Make a changeset obsolete without successors.

This an important operation as it should mostly replace *strip*.

Alternative names:

- kill: shall has funny effects when you forget "hg" in front of ``hg kill``.
- obsolete: too vague, too long and too generic.

evolve
``````

Automatically resolve *troublesome* changesets
(*orphan*, *phase-divergent* and *content-divergent*)

This is an important name as hg pull/push will suggest it the same way it
suggest merging when you add heads.

Alternative names:

- solve (too generic ?)
- stabilize