-----------------------------------------------------
Implementation of Obsolete Marker
-----------------------------------------------------
.. warning:: This document is still in heavy work in progress

Various technical details
-----------------------------------------------------

Some stuff that worse to note. some may deserve their own section later.

storing old changeset
``````````````````````

The new general delta format allow a very efficient storage of two very similar
changesets. Storing obsolete childrens using general delta takes no more place
than storing the obsolete diff. Reverted file will even we reused. The whole
operation will take much less space the strip backup.


Abstraction from history rewriting UI
```````````````````````````````````````````

How Mercurial handle obsolete marker is independent from what create
them and what actual operation solves error case. Any of the existing history
rewriting UI (rebase, mq, histedit) can lay obsolete marker and resolve
situation created by other. To go further a hook system of obsolete marker
creation would allow each mechanism to collaborate with other though a standard
and central mechanism.

Obsolete marker content
```````````````````````````

In the current implementation obsolete marker contains::

    'id': "unique id of the obsolete marker"
    'subjects': "0-N newer version of changeset in "object" (as ordered list)
    'object': "old and obsolete version"
    'date': "When was this marker created ?"
    'user': "Who did that ?"
    'reason': "Why was it done"

Grouping them for operation that create multiple markers are once may be a good
idea. (would help, exchange and cancelation)

Obsolete marker storage
```````````````````````````

Obsolete marker will most likely be stored outside standard history. They are
multiple reasons for that:


First, obsolete markers are really perpendicular to standard history there is not
strong reason to include it here other than convenience.

Second, storing obsolete marker inside standard history means:


* A changeset must be created every time an obsolete relation is added. Very
  inconvenient for delete operation.

* Obsolete marker must be forged at the creation of the new changeset. This
  is very inconvenient for split operation. And in general it become
  complicated to fix history afterward in particular when working with older
  client.

Storing obsolete marker outside history have several pro:

* It ease Exchange of obsolete marker without unnecessary obsolete changeset content

* It allow tuning the actual storage and protocol exchange while maintaining
  compatibility with older client through the wire (as we do the repository
  format)

* ease the exchange of obsolete related information during discovery to exchange
  obsolete changeset relevant to conflict resolution. Exchanging such
  information deserve a dedicated protocol.

Persistent
```````````````````````

*Extinct* changeset and obsolete marker will most likely be garbage collected as
some point. However, archive server may decide to keep them forever in order to
keep a fully auditable history in it's finest conception.


Current status
-----------------------------------------------------

An experimental implementatione exists. What have been done so far.


* rich markers stored outside history,
* obsolete markers exchange through pushkey,

* compute obsolete-tip (newest version of a changeset)

* compute obsolete, unstable, extinct and suspended set.

* hidden extinct changesets for UI.

* Require `--force` to push unstable history.

* Use secret phase to remove extinct changesets from discovery.

* alter rebase to use obsolete marker instead of stripping. (XXX break --keep for now)

* Have an experimental mq-like extension to rewrite history (more on that later)

* Have an extension to update and mq repository according evolution of standard (more on that later)