--- a/docs/obs-concept.rst Mon Mar 26 18:24:39 2012 +0200
+++ b/docs/obs-concept.rst Tue Mar 27 16:50:14 2012 +0200
@@ -1,26 +1,99 @@
--------------------------
-Obsolete Marker Concept
--------------------------
+-----------------------------------------------------------
+Why Do We Need a New Concept
+-----------------------------------------------------------
+
+Current DVCS are great tool to forge a series of flawless changeset on your own.
+But they perform poorly whe is comes to **share** work in progress and
+**collaborate** on such work in progress.
+
+When people forge new version of a changeset they create a new changeset and get
+ride of the original changeset. Difficultis to collaborate mostly came from the
+way old content are *removed* from repository.
+
+Mercurial Approach: Strip
+-----------------------------------------------------
+
+With current version of mercurial, every changesets that exist in your
+repository are *visible* and *meaningful*. To get ride of old changeset you
+rewrote mercurial remove them from the repository storage. with an operation
+called *strip*. After the *strip* the repository looks like if the changeset
+never existed.
+
+This approach is simple and effective but have a very big drawnback: You can
+remove changesets from **your repository only**. If strip exists in other
+repositories it will show of again and again. This only cure for this is to
+strip the offending changeset from all repository. And operation at best
+impractical and in most case impossible!
-Obsolete marker is a powerful concept that allow mercurial to safely handle
-history rewriting operations. It is a new type of relation between Mercurial
-changesets that track the result of history rewriting operations.
+As consequence, **you can not rewrite something once you exchange it with
+others**. The old version will still exists along side the new one [#]_.
-This concept is simple to define and provides a very solid base to:
+Moreover backup are create stripped changeset in most case. This allow
+restoration of old changeset but the process is painful.
+
+Finally, as the repository format is not optimized for deletion. stripping a
+changeset may be slow in some situation.
-- Very fast history rewriting operations,
+To sum up, the strip approach is very simple but does not handle interaction
+with the outer world. Which is unfortunate for a *Distributed* VCS.
+
+.. [#] various work around exists but they are work around with their own flow.
+
+Git Approach: Overwrite Reference
+-----------------------------------------------------
+
+Git approach for repository is a bit more complex: They can be any amount of
+changeset can exist in a repository. but **only changesets referenced by a git
+branch** are *visible* and *meaningful*.
+
-- auditable and reversible history rewritting process,
+.. warning:: add a schema::
-- clean final history,
+ C
+ | B---<foo>
+ |/
+ |
+ A
+
+ Only B and A are visible.
+
+This ease the process of getting ride of old changeset. You can just leave them
+in place and move the reference on the new one. You can then propagate those
+change by moving the git-branch on remote host, newer version overwritting the
+older one.
-- share and collaborate on mutable part of the history,
+This approach goes a bit further but still have major drawback:
+
+
+Because you **overwrite** git-branch you have no conflit resolution. The last
+to spoke win. This make collaboration on multiple changeset difficult because
+you can't merge concurent update on changeset.
+
+Every overwrite is forced operation where the operator say "Yes I want this to
+replace that. On higly distributed environment user may end with conflicting
+reference with and no proper way to choose.
+
+Because of this way to visualize a repository, git-branches are a very core
+part of git. This make user interface more complicated and move through history
+more constrainted.
-- gracefully handle history rewriting conflict,
+Finally, even if all older changeset still exist in the repository acces to them
+is still painful.
+
+
+-----------------------------------------------------
+The Obsolete Marker Concept
+-----------------------------------------------------
-- allows various history rewriting UI to collaborate with a underlying common API.
+
+
+
+
+As None of the concept was powerful enough to embrace the need to safely rewrite
+history, easily share and collaborate on mutable history we needed another one.
+
Basic concept
@@ -30,9 +103,7 @@
Every history rewriting operation stores the information that old rewritten
changesets has newer version available in a set of changeset.
-This simple rules allows to express any possible history rewriting operation:
-
-
+All basic history rewriting operation can create a appropriate obsolete marker.
.. figure:: ./figures/example-1-update.*
@@ -252,3 +323,65 @@
.. warning:: add a schema
+
+Conclusion
+----------------
+
+Obsolete marker is a powerful concept that allow mercurial to safely handle
+history rewriting operations. It is a new type of relation between Mercurial
+changesets that track the result of history rewriting operations.
+
+This concept is simple to define and provides a very solid base to:
+
+
+- Very fast history rewriting operations,
+
+- auditable and reversible history rewritting process,
+
+- clean final history,
+
+- share and collaborate on mutable part of the history,
+
+- gracefully handle history rewriting conflict,
+
+- allows various history rewriting UI to collaborate with a underlying common API.
+
+.. list-table:: Comparison on solution [#]_
+ :header-rows: 1
+
+ * - Solution
+ - Remove changeset locally
+ - Works on any point of your history
+ - Propagation
+ - Collaboration
+ - Speed
+ - Access to older version
+
+ * - Strip
+ - `+`
+ - `+`
+ - \
+ - \
+ - \
+ - `- -`
+
+ * - Reference
+ - `+`
+ - \
+ - `+`
+ - \
+ - `+`
+ - `-`
+
+ * - Obsolete
+ - `+`
+ - `+`
+ - `++`
+ - `++`
+ - `+`
+ - `+`
+
+
+
+.. [#] To preserve good tradition in comparison table, an overwhelming advantage
+ goes to the defended solution.