Mercurial > evolve
changeset 166:8f8a52cd0b9f
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 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.