-----------------------------------------------------------

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.