comparison docs/concepts.rst @ 4619:93514c421528

docs: change `troubled` references to `unstable`

Per https://www.mercurial-scm.org/wiki/CEDVocabulary

4618:803d32f4e498

(If you prefer a calculus metaphor to set theory, it might help to
think of the traditional parent/child DAG as the first derivative of
your source code, and the obsolescence DAG as the second derivative.)

Troubled changesets (orphan, bumped, divergent)
-----------------------------------------------

Evolving history can introduce problems that need to be solved. For
example, if you prune a changeset *P* but not its descendants, those
descendants are now on thin ice. To push a changeset to another

changeset *C* to have different successors. When this happens, the
successors are both called *divergent* (unless one of them is in
public phase; only mutable changesets are divergent).

The collective term for orphan, bumped, and divergent changeset is
*troubled*::

  troubled = orphan ∪ bumped ∪ divergent

It is possible for a changeset to be in any of the troubled categories
at the same time: it might be an orphan and divergent, or bumped and
divergent, or whatever.

  [diagram: Venn diagram of troubled changesets, showing overlap]

The presence of troubled changesets indicates the need to run ``hg
evolve``.

Hidden (and visible) changesets
-------------------------------

  hideable = obsolete
  blockers = bookmarks ∪ parents(workingcopy) ∪ localtags
  hidden = hideable ∖ ancestors((repo ∖ hideable) ∪ blockers)

This will probably be clearer with a worked example. First, here's a
repository with some obsolete changesets, some troubled changesets,
one bookmark, a working copy, and some hidden changesets::

        x-x
       /
  -o-o-o-o

4619:93514c421528

(If you prefer a calculus metaphor to set theory, it might help to
think of the traditional parent/child DAG as the first derivative of
your source code, and the obsolescence DAG as the second derivative.)

Unstable changesets (orphan, bumped, divergent)
-----------------------------------------------

Evolving history can introduce problems that need to be solved. For
example, if you prune a changeset *P* but not its descendants, those
descendants are now on thin ice. To push a changeset to another

changeset *C* to have different successors. When this happens, the
successors are both called *divergent* (unless one of them is in
public phase; only mutable changesets are divergent).

The collective term for orphan, bumped, and divergent changeset is
*unstable*::

  unstable = orphan ∪ bumped ∪ divergent

It is possible for a changeset to be in any of the unstable categories
at the same time: it might be an orphan and divergent, or bumped and
divergent, or whatever.

  [diagram: Venn diagram of unstable changesets, showing overlap]

The presence of unstable changesets indicates the need to run ``hg
evolve``.

Hidden (and visible) changesets
-------------------------------

  hideable = obsolete
  blockers = bookmarks ∪ parents(workingcopy) ∪ localtags
  hidden = hideable ∖ ancestors((repo ∖ hideable) ∪ blockers)

This will probably be clearer with a worked example. First, here's a
repository with some obsolete changesets, some unstable changesets,
one bookmark, a working copy, and some hidden changesets::

        x-x
       /
  -o-o-o-o