Source

mutable-history / docs / obs-terms.rst

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

Changeset in either draft or secret phases.

obsolete

Obsolete changesets are mutable changeset used as a precursors.

A changeset is used as a precursors when at least one obsolete refer to it in the precursors field.

extinct

Extinct changesets are obsolete one with obsolete only descendants.

They can be safely:

  • hidden in the UI,
  • silently excluded from pp 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

Troublesome commit have unresolved issue caused by obsolete relations.

Possible issues are listed in the next column. It is possible for troublesome changeset to combine multiple issue at once. (eg: conflicting and unstable)

(possible alternative name: unsettled, troubled)

unstable

Unstable changesets are changesets with obsolete ancestors.

They must be rebased on a better base to solve the situation.

(possible alternative name: precarious)

latecomer

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.