annotate docs/evolve-collaboration.rst @ 167:64c886d26aab

add auc user story

------------------------------------------------
Collaboration Using Evolve: A user story
------------------------------------------------


After having written some code for ticket #42, M W. start a patch (this
will be kind of like a 'work-in-progress' checkpoint initially)::

    $ ci -m '[entities] remove magic'

Instant patch ! Note how the default phase of this changeset is (still)
in "draft" state.

This is easily checkable::

    $ hg phase tip
    827: draft

See ? Until the day it becomes a "public" changeset, this can be altered
to no end. How ? It happens with an explicit::

    $ hg phase -p

In practice, pushing to a "publishing" repository can also turn draft
changesets into public ones. Older mercurial releases are automatically
"publishing" since they do not have the notion of non-public changesets
(or mutable history).

In the transition ... phase from older mercurial servers, this will
happen often, so be careful.

Now let's come back to our patch. Next hour sees good progress and W.
wants to complete the patch with the recent stuff (all that's shown by
an "hg diff") to share with a co-worker (let's call him C.W.)::

    $ hg amend -m '[entities] fix frobulator (closes #42)'

Note that we also fix the commit message. (For recovering mq users: this
is just like "hg qrefresh -m").

Before leaving, let's push to the central shared repository. That will
give C.W. the signal that something is ripe for review / further amendments::

    $ hg push # was done with a modern mercurial, draft phase is preserved

The next day, Mr C.W, which arrives very very early, can immediately
work out some glitches in the patch.

He then starts another one, for ticket #43 and finally commits it.
Then, as original worker arrives, he pushes his stuff.

M W., now equipped with enough properly sugared coffee to survive the
next two hours::

    $ hg pull

Then::

    $ hg up "tip ~ 1"

brings him to yesterday's patch. Indeed the patch serial number has
increased (827 still exists but has been obsoleted).

He understands that his original patch has been altered. But how did it
evolve ?

The enhanced hgview shows the two patches. By default only the most
recent version of a patch is shown.

Now, when W. installed the mutable-history extensions, he got an alias
that allows him to see the diff between two amendments, defined like this::

    odiff=diff --rev 'limit(obsparents(.),1)' --rev .

He can see exactly how C.W. amended his work.

* odiff