Mercurial > hg > mutable-history

changeset 166:8f8a52cd0b9f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
big doc update
author Pierre-Yves David <pierre-yves.david@logilab.fr>
date Tue, 27 Mar 2012 16:50:14 +0200
parents ef6113f3d38e
children 64c886d26aab
files docs/conf.py docs/index.rst docs/obs-concept.rst
diffstat 3 files changed, 220 insertions(+), 38 deletions(-) [+]
line wrap: on
line diff
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -65,7 +65,7 @@
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 html_title = project
-#html_theme = 
+html_theme = 'haiku'
 html_theme_path = ['.']
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,48 +4,48 @@
 
 
 Here are various Materials on planned improvement to mercurial regarding
-rewriting mutable history.
+rewriting history.
 
-The effort  split in two part:
+The effort  splits in two parts:
 
- * The **obsolete marker** concept aiming to provide and alternative to strip to
-   get ride of changesets.
+ * The **obsolete marker** concept aims to provide and alternative to ``strip``
+   to get ride of changesets.
 
- * A mercurial extension: **evolve** that rewrite using *obsolete marker*
+ * The **evolve** mercurial extension to rewrite history using *obsolete marker*
    under the hood.
 
 
-regarding mercurial internals, the first and most important step is the
-**obsolete marker**. However most user will never be directly exposed to the
-concept. For this reason document about changeset evolution are put first.
+The first and most important step is by far the **obsolete marker**. However
+most user will never be directly exposed to the concept. For this reason
+document about changeset evolution are put first.
 
 
 Evolve: A robust alternative to MQ
 ====================================
 
-Evolve is an experimental history rewriting extensions that use the obsolete
-marker. It is inspired from MQ and pbranch but have multiple advantage over
-them.
+Evolve is an experimental history rewriting extensions that use obsolete
+markers. It is inspired from MQ and pbranch but have multiple advantage over
+them:
 
 * sticks to "Work where you are" philosophy (I'll need better wording
   for that)
 
-* Handle any kind history. Even history with branch and merge.
+* Handle **non-linear history with branches and merges**
 
-* Use robust mercurial's merge mechanism 
+* Use **robust merge** mechanism of mercurial.
 
   simple conflict are handled by real merge tools using appropriate ancestor.
   Conflict are much rarer and much more user friendly.
 
-* All mutable history available at the same time
+*  Mutable history **fully available all the time**.
 
   You are do not need to unapply and apply patche to access various part of you
   history.
 
-* Use plain changeset only. Evole create and exchange real changeset only. 
+* Use **plain changeset** only. Evole create and exchange real changeset only. 
   Mutable history can be used in all usual operation 'pull, push, log, diff …)
 
-* Allow sharing and collaborating mutable history without fear of duplicate.
+* Allow **sharing and collaboration** mutable history without fear of duplicate.
   (thanks to obsolete marker).
 
 * Cover all mq usage but guard.
@@ -62,9 +62,19 @@
     $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/mutable-history/
     $ mutable-history/enable.sh > ~/.hgrc
 
+You will probably want to use the associated version of hgview (QT viewer only)
+
+    $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/hgview/
+    $ cd hgview
+    $ python setup.py install --user
+
+
+ ---
+
+For more information see documents below
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    tutorial
    evolve-faq
@@ -73,14 +83,32 @@
 Smart changeset deletion: Obselete Marker
 ==========================================
 
-for dev and advanced user
+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.
+
+ ---
+
+For more information see documents below
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    obs-concept
-   glossary
    obs-implementation
 
 
@@ -91,4 +119,25 @@
 Know canveas
 =================================
 
-Big flashy warning on current remaining issue
+Here is a list of know issue that will be fixed later:
+
+* Unstable changeset turns secret.
+
+* ``hg stabilize`` does not handle conflict.
+
+* Mercurial think you are pushing additional heads even when the new head
+  obsolete another one. You have to use hg push -f more than necessary.
+
+* ``hg update`` can move an obsolete parent
+
+* you need to provideto graft --continue -O if you started you graft using -O.
+
+
+
+
+
+Anexe
+=================================
+
+.. toctree::
+   glossary
--- a/docs/obs-concept.rst
+++ b/docs/obs-concept.rst
@@ -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.