# states.py - introduce the state concept for mercurial changeset

#

# Copyright 2011 Pierre-Yves David <pierre-yves.david@ens-lyon.org>

#                Logilab SA        <contact@logilab.fr>

#                Augie Fackler     <durin42@gmail.com>

#

# This software may be used and distributed according to the terms of the

# GNU General Public License version 2 or any later version.

'''introduce the state concept for mercurial changeset

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

General concept

===============

This extension adds the state concept. A changeset are now in a specific state

that control they mutability and they exchange.

States properties

.................

The states extension currently alter two property for changeset

:mutability:  history rewritten tool should refuse to work on immutable changeset

:sharing:     shared changeset are exchanged during pull and push. other are not

Here is a small summary of the current property of state existing state::

    ||           || mutable || shared ||

    || published ||         ||   x    ||

    || ready     ||    x    ||   x    ||

    || draft     ||    x    ||        ||

States consistency and ordering

...............................

States of changesets have to be consistent with each other. A changeset can only have ancestors of it's state (or a compatible states)

Example:

    A ``published`` changeset can't have a ``draft`` parent.

a state is compatible with itself and all "smaller" states. Order is as follow::

    published < ready < draft

.. note:

    This section if probably far too conceptual for people. The result is just

    that: A ``published`` changeset can only have ``published`` ancestors. A

    ``ready`` changeset can only have ``published`` or ``ready`` ancestors.

    Moreover There is a need for a nice word to refer to "a state smaller than another"

States details

==============

published

    Changesets in the ``published`` state are the core of the history.  They are

    changesets that you published to the world. People can expect them to always

    exist. They are changesets as you know them. **By default all changesets

    are published**

    - They are exchanged with other repositories (included in pull//push).

    - They are not mutable, extensions rewriting history should refuse to

      rewrite them.

ready

    Changesets in the ``ready`` state have not yet been accepted in the

    immutable history. You can share them with others for review, testing or

    improvement. Any ``ready`` changeset can either be included in the

    published history (and become immutable) or be rewritten and never make it

    to the published history.

    - They are exchanged with other repositories (included in pull//push).

    - They are mutable, extensions rewriting history accept to work on them.

draft

    Changesets in the ``draft`` state are heavy work in progress you are not

    yet willing to share with others.

    - They are not exchanged with other repositories. pull//push do not see them.

    - They are mutable, extensions rewriting history accept to work on them.

--

.. note:

    The Dead states mentionned in on the wiki page are missing. There is two main reason for it:

    1. The ``dead`` state has a different behaviour that requires more work to be

       implemented.

    2. I believe that the use cases of ``dead changeset`` are better covered by

       the ``obsolete`` extension.

--

.. note:

    I'm tempted to add a state with the same property that ``ready`` for review

    workflow.::

        ||           || mutable || shared ||

        || published ||         ||   x    ||

        || ready     ||    x    ||   x    ||

        || inprogress||    x    ||   x    ||

        || draft     ||    x    ||        ||

    The ``ready`` state would be for changeset that wait review of someone that

    can "publish" them.

Current Feature and usage

=========================

Enabling states

...............

The extension adds a :hg:`hg states` command to display and choose which states

are used by a repository, see :hg:`hg states` for details.

By default all changesets in the repository are ``published``. Other states

must be explicitly activated. Changeset in a remote repository that doesn't

support states are all seen as ``published``.

.. note:

    When a state is not activated, changesets in this state are handled as

    changesets of the previous state it (``draft`` are handled as ``ready``,

    ``ready`` are handled as ``published``).

TODO:

- have a configuration in hgrc::

    [states]

    ready=(off|on)(-inherit)?

    <state>=(off|on)(-inherit)?

 :off:     state disabled for new repo

 :on:      state enabled  for new repo

 :inherit: if present, inherit states of source on :hg:`clone`.

-  have a switch to select if changesets do change state on state activation.

- display the number of changesets that change state when activating a state.

State transition

................

Changeset you create locally will be in the ``draft`` state. (or any previous

state if draft isn't enabled)

There is some situation where the state of a changeset will change

automatically. Automatic movement always go in the same direction.: ``draft ->

``ready`` -> ``published``

1. When you pull or push boundary move. Common changeset that are ``published`` in

one of the two repository are set to ``published``. Same goes for ``ready`` etc

(states are evaluated from in increasing order XXX I bet no one understand this

parenthesis. Pull operation alter the local repository. push alter both local

and remote repository.

.. note:

    As Repository without any specific state have all their changeset

    ``published``, Pushing to such repo will ``publish`` all common changeset.

2. Tagged changeset get automatically Published. The tagging changeset is

tagged too... This doesn't apply to local tag.

You can also manually change changeset state with a dedicated command for each

state. See :hg:`published`, :hg:`ready` and :hg:`draft` for details.

XXX maybe we can details the general behaviour here

:hg <state> revs:                 move boundary of state so it includes revs

                                  ( revs included in ::<state>heads())

:hg --exact <state> revs:         move boundary so that revs are exactly in state

                                  <state> ( all([rev.state == <state> for rev in

                                  revs]))

:hg --exact --force <state> revs: move boundary event if it create inconsistency

                                  (with tag for example)

TODO:

- implement --exact

- implement consistency check

- implement --force

Existing command change

.......................

As said in the previous section:

:commit:    Create draft changeset (or the first enabled previous changeset).

:tag:       Move tagged and tagging changeset in the ``published`` state.

:incoming:  Exclude ``draft`` changeset of remote repository.

:outgoing:  Exclude ``draft`` changeset of local repository.

:pull:      As :hg:`in`  + change state of local changeset according to remote side.

:push:      As :hg:`out` + sync state of common changeset on both side

:rollback:  rollback restore states heads as before the last transaction (see bookmark)

State Transition control

.........................

There is currently no way to control who can alter boundary (The most notable

usecase is about the published one).

This is probably needed quickly

XXX TODO: Proper behaviour when heads file are chmoded whould be a first step.

XXX We are going to need hooks (pre and post) hook on state transition too.

Template

........

A new template keyword ``{state}`` has been added.

Revset

......

We add new ``readyheads()`` and ``publishedheads()`` revset directives. This

returns the heads of each state **as if all of them were activated**.

XXX TODO - I would like to

- move the current ``<state>heads()`` directives to

  _``<state>heads()``

- add ``<state>heads()`` directives to that return the currently in used heads

- add ``<state>()`` directives that match all node in a state.

Context

.......

The ``context`` class gain a new method  ``states()`` that return a ``state`` object. The

most notable property of this states object are ```name`` and ``mutable``.

Other extensions

................

:rebase:     can't rebase immutable changeset.

:mq:         can't qimport immutable changeset.

TODO: publishing a changeset should qfinish mq patches.

Implementation

==============

State definition

................

Conceptually:

The set of node in the states are defined by the set of the state heads. This allow

easy storage, exchange and consistency.

.. note: A cache of the complete set of node that belong to a states will

         probably be need for performance.

Code wise:

There is a ``state`` class that hold the state property and several useful

logic (name, revset entry etc).

All defined states are accessible thought the STATES tuple at the ROOT of the

module. Or the STATESMAP dictionary that allow to fetch a state from it's

name.

You can get and edit the list head node that define a state with two methods on

repo.

:stateheads(<state>):        Returns the list of heads node that define a states

:setstate(<state>, [nodes]): Move states boundary forward to include the given

                             nodes in the given states.

Those methods handle ``node`` and not rev as it seems more resilient to me that

rev in a mutable world. Maybe it' would make more sens to have ``node`` store

on disk but revision in the code.

Storage

.......

States related data are stored in the ``.hg/states/`` directory.

The ``.hg/states/Enabled`` file list the states enabled in this

repository. This data is *not* stored in the .hg/hgrc because the .hg/hgrc

might be ignored for trust reason. As missing und with states can be pretty

annoying. (publishing unfinalized changeset, pulling draft one etc) we don't

want trust issue to interfer with enabled states information.

``.hg/states/<state>-heads`` file list the nodes that define a states.

_NOSHARE filtering

..................

Any changeset in a state with a _NOSHARE property will be exclude from pull,

push, clone, incoming, outgoing and bundle. It is done through three mechanism:

1. Wrapping the findcommonincoming and findcommonoutgoing code with (not very

   efficient) logic that recompute the exchanged heads.

2. Altering ``heads`` wireprotocol command to return sharead heads.

3. Disabling hardlink cloning when there is _NOSHARE changeset available.

Internal plumbery

-----------------

sum up of what we do:

* state are object

* repo.__class__ is extended

* discovery is wrapped up

* wire protocol is patched

* transaction and rollback mechanism are wrapped up.

* XXX we write new version of the boundard whenever something happen. We need a

  smarter and faster way to do this.

'''

import os

from functools import partial

from mercurial.i18n import _

from mercurial import cmdutil

from mercurial import scmutil

from mercurial import context

from mercurial import revset

from mercurial import templatekw

from mercurial import util

from mercurial import node

from mercurial.node import nullid, hex, short

from mercurial import discovery

from mercurial import extensions

from mercurial import wireproto

from mercurial import pushkey

from mercurial import error

from mercurial.lock import release

# states property constante

_NOSHARE=2

_MUTABLE=1

class state(object):

    """State of changeset

    An utility object that handle several behaviour and containts useful code

    A state is defined by:

        - It's name

        - It's property (defined right above)

        - It's next state.

    XXX maybe we could stick description of the state semantic here.

    """

    # plumbery utily

    def __init__(self, name, properties=0, next=None):

        self.name = name

        self.properties = properties

        assert next is None or self < next

        self.next = next

    @util.propertycache

    def trackheads(self):

        """Do we need to track heads of changeset in this state ?

        We don't need to track heads for the last state as this is repo heads"""

        return self.next is not None

    # public utility

    def __cmp__(self, other):

        """Use property to compare states.

        This is a naiv approach that assume the  the next state are strictly

        more property than the one before

        # assert min(self, other).properties = self.properties & other.properties

        """

        return cmp(self.properties, other.properties)

    @property

    def mutable(self):

        return bool(self.properties & _MUTABLE)

    # display code

    def __repr__(self):

        return 'state(%s)' % self.name

    def __str__(self):

        return self.name

    # revset utility

    @util.propertycache

    def _revsetheads(self):

        """function to be used by revset to finds heads of this states"""

        assert self.trackheads

        def revsetheads(repo, subset, x):

            args = revset.getargs(x, 0, 0, 'publicheads takes no arguments')

            heads = []

            for h in repo._statesheads[self]:

                try:

                    heads.append(repo.changelog.rev(h))

                except error.LookupError:

                    pass

            heads.sort()

            return heads

        return revsetheads

    @util.propertycache

    def headssymbol(self):

        """name of the revset symbols"""

        if self.trackheads:

            return "%sheads" % self.name

        else:

            return 'heads'

# Actual state definition

ST2 = state('draft', _NOSHARE | _MUTABLE)

ST1 = state('ready', _MUTABLE, next=ST2)

ST0 = state('published', next=ST1)

# all available state

STATES = (ST0, ST1, ST2)

# all available state by name

STATESMAP =dict([(st.name, st) for st in STATES])