diff docs/obs-implementation.rst @ 161:4e3f25ba5401

More doc and index with sphynx

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/obs-implementation.rst	Tue Mar 20 19:26:55 2012 +0100
@@ -0,0 +1,97 @@
+
+-----------------------------------------------------
+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 who decide to create
+them and what actual operation solve 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 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.
+
+
+* 1-1 obsolete marker stored outside history,
+
+* compute obsolete-tip
+
+* obsolete marker exchange through pushkey,
+
+* compute obsolete, unstable, extinct and suspended set.
+
+* hidden extinct changesets for UI.
+
+* Use secret phase to remove from discovery obsolete and unstable changeset (to
+  be improved soon)
+
+* 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)
+