view README @ 33:dca86448d736

Add some doc.

=============================
Mutable History For Mercurial
=============================

This repository hold several experimental extension that introduce concept
related to history rewriting in mercurial. You will find three different
extensions.

:states:

    Introduce a state concept. It allow to track which changeset have been make
    public and immutable and which you want to keep local.

:obsolete:

    Introduce an obsolete concept that track new version of rewritten changeset.

:rewrite:
    A collection of command to rewrite the mutable part of the history.



**These extensions are experimental and are not meant for production.**


States Extension
======================

state: experimentally functional

(see http://mercurial.selenic.com/wiki/StatesPlan)

This extension the state concept. A changeset now have one of the following *state*:

:published:

    Changeset in the ``published`` state are the core of the history.  They are
    changeset that you published to the world. People can expect them to always
    be exist. This is changeset as you know them. **By default all changeset
    are published**

    * They are exchanged with other repository (included in pull//push).

    * They are not mutable, extension rewriting history should refuse to
      rewrite them.

:ready:

    Changeset in the ``ready`` state have not been accepted in the immutable
    history yet. You can share them with other for review, testing or
    improvement. Any ``ready`` changeset can either be included in the
    published history (and become immutable) or be rewritten and rever make it
    the published history.

    * They are exchanged with other repository (included in pull//push).
    * They are mutable, extension rewriting history accept to work on them.

:draft:

    Changeset in the ``draft`` state are heavy work in progress you are
    currently working on without willing to share with other.

    * They are not exchanged with other repository. pull//push does not see them.
    * They are mutable, extension rewriting history accept to work on them.


State of changeset have to be consistent with each other. A ``published``
changeset can only have ``published`` ancestors. A ``ready`` changeset can only
have ``published`` or ready ancestor.


Usage and Feature
------------------

By default all changeset in the repository are ``published``. Other state must
be explicitly activated. When a state is not activated, changeset of this state
are handled as changeset of the state before him. (``draft`` are handled as
``ready``, ``ready`` are handled as ``published``)

Changeset will automatically move to ``published`` state when:

* pushed to a repo that doesn't support ``ready`` state.

* Tagged by a non local tag.

Commands
........

The extension add and ``hg states`` command to choose which state are used by a
repository, see ``hg help states for details``.

A command is also added for all active states. The command have the name of the
states and is used to manually change the state of a changeset. This is mainly
usefull to move changeset from ``draft`` to ``ready``.:: 

    hg ready tip

Template
........

A new template keyword ``{state}`` have been added

Revset
........

We add a new ``readyheads()`` and ``publishedheads()`` revset directive. This return the heads of each states **as if all of them was activated**.

FAQ
---

Why to you store activate state ouside ``.hg/hgrc``
....................................................

``.hg/hgrc`` might be ignored for trust reason. we don't want the 

Why is the ``dead`` state missing
....................................................

1. The ``dead`` state have a different behaviour that require more work to be
implemented

2. I believe that the usecase of ``dead changeset`` are better covered by the
``obsolete`` extension.

To Do
-----

* Moving boundary backward (code existist in ``liquid`` extension done at the
  CPH sprint)

* support for default value in configuration (when for init and clone)

* stronger pull//push support (unknown remote head confuse the current code)

* display the number of changeset that change state when activating a state.

* have a switch to select if changeset do change state on state activation.

* proper revset directive.




Obsolete Extension
======================

state: in progress

Usage and Feature
------------------

obsolete changeset are hidden.

Commands
........


a ``debugobsolete`` command have been added.


To Do
-----

* do not exchange them

* handle non-obsolete children

* exchange the obsolete information

* refuse to obsolete published changeset

* handle split

* handle conflict

* handle out of sync

rewrite Extension
======================

state: To be written