--- a/docs/conf.py Mon Mar 26 18:24:39 2012 +0200
+++ b/docs/conf.py Tue Mar 27 16:50:14 2012 +0200
@@ -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 Mon Mar 26 18:24:39 2012 +0200
+++ b/docs/index.rst Tue Mar 27 16:50:14 2012 +0200
@@ -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 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.