diff README @ 33:dca86448d736

Add some doc.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Mon Aug 01 14:12:48 2011 +0200
@@ -0,0 +1,182 @@
+=============================
+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
+