docs/obs-concept.rst
changeset 166 8f8a52cd0b9f
parent 163 92b073d13f2d
child 173 4d44a37d51d1
child 175 f86ed5a82723
--- 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.