annotate docs/index.rst @ 194:b7145eed54fe

add a known issu

========================================
Safe Mutable History
========================================


Here are various Materials on planned improvement to mercurial regarding
rewriting history.

The effort  splits in two parts:

 * The **obsolete marker** concept aims to provide and alternative to ``strip``
   to get ride of changesets.

 * The **evolve** mercurial extension to rewrite history using *obsolete marker*
   under the hood.


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 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 **non-linear history with branches and merges**

* 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.

*  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. 
  Mutable history can be used in all usual operation 'pull, push, log, diff …)

* Allow **sharing and collaboration** mutable history without fear of duplicate.
  (thanks to obsolete marker).

* Cover all mq usage but guard.

.. warning:: The evolve extention and the obsolete marker are at an experimental
            stage. While using obsolet you'll likely be exposed to complexe
            implication of the **obsolete marker** concept. I do not recommend
            non power user to test this at this stage.

            Production ready version should hide such details to normal user.

To enable the evolve extension use::

    $ 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: 2

   tutorial
   evolve-faq
   from-mq
   evolve-collaboration
   qsync

Smart changeset deletion: Obsolete Marker
==========================================

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: 2

   obs-concept
   obs-implementation






Know canveas
=================================

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.

* hg graphlog show extinct changeset

* hg heads show extinct changeset

* hg merge considered extinct head as valid target. requiring you to manually
  specify target all the time.

* obsolete relation exchange crash (as in traceback) on static http repo.





Annexe
=================================

.. toctree::
   :maxdepth: 1

   glossary