docs/evolve-collaboration.rst
author Pierre-Yves David <pierre-yves.david@logilab.fr>
Mon, 03 Dec 2012 15:13:50 +0100
branchstable
changeset 627 28d79c21cc3a
parent 527 b81193ef3488
child 655 dd5765ae91c3
permissions -rw-r--r--
update changelog
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
519
9825c7da5b54 ensure all file have a copyright notice
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 492
diff changeset
     1
.. Copyright 2011 Pierre-Yves David <pierre-yves.david@ens-lyon.org>
9825c7da5b54 ensure all file have a copyright notice
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 492
diff changeset
     2
..                Logilab SA        <contact@logilab.fr>
527
b81193ef3488 docs: add missing blank line after Copyright notice
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 519
diff changeset
     3
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     4
------------------------------------------------
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     5
Collaboration Using Evolve: A user story
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     6
------------------------------------------------
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     7
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     8
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
     9
After having written some code for ticket #42, Alice starts a patch
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    10
(this will be kind of like a 'work-in-progress' checkpoint
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    11
initially)::
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    12
181
35baa2a80073 docs: fix typos in evolve collaboration.
Arne Babenhauserheide <bab@draketo.de>
parents: 167
diff changeset
    13
    $ hg ci -m '[entities] remove magic'
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    14
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    15
Instant patch ! Note how the default phase of this changeset is (still)
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    16
in "draft" state.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    17
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    18
This is easily checkable::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    19
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    20
    $ hg phase tip
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    21
    827: draft
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    22
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    23
See? Until the day it becomes a "public" changeset, this can be
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    24
altered to no end. How? It happens with an explicit::
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    25
232
adb7e29cb2bd docs: proof-read and review
Benoit Allard <benoit@aeteurope.nl>
parents: 189
diff changeset
    26
    $ hg phase --public
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    27
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    28
In practice, pushing to a "publishing" repository can also turn draft
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    29
changesets into public ones. Older Mercurial releases are automatically
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    30
"publishing" since they do not have the notion of non-public changesets
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    31
(or mutable history).
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    32
181
35baa2a80073 docs: fix typos in evolve collaboration.
Arne Babenhauserheide <bab@draketo.de>
parents: 167
diff changeset
    33
During the transition from older mercurial servers to new ones, this will
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    34
happen often, so be careful.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    35
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    36
Now let's come back to our patch. Next hour sees good progress and Alice
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    37
wants to complete the patch with the recent stuff (all that's shown by
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    38
an "hg diff") to share with a co-worker, Bob::
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    39
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    40
    $ hg amend -m '[entities] fix frobulator (closes #42)'
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    41
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    42
Note that we also fix the commit message. (For recovering mq users: this
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    43
is just like "hg qrefresh -m").
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    44
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    45
Before leaving, let's push to the central shared repository. That will
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    46
give Bob the signal that something is ripe for review / further amendments::
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    47
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    48
    $ hg push # was done with a modern mercurial, draft phase is preserved
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    49
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    50
The next day, Bob, who arrives very early, can immediately work out
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    51
some glitches in the patch.
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    52
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    53
He then starts two others, for ticket #43 and #44 and finally commits them.
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    54
Then, as original worker arrives, he pushes his stuff.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    55
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    56
Alice, now equipped with enough properly sugared coffee to survive the
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    57
next two hours::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    58
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    59
    $ hg pull
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    60
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    61
Then::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    62
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    63
    $ hg up "tip ~ 2"
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    64
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    65
brings her to yesterday's patch. Indeed the patch serial number has
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    66
increased (827 still exists but has been obsoleted).
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    67
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    68
She understands that his original patch has been altered. But how did it
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    69
evolve?
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    70
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    71
The enhanced hgview shows the two patches. By default only the most
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    72
recent version of a patch is shown.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    73
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    74
Now, when Alice installed the mutable-history extensions, she got an alias
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    75
that allows her to see the diff between two amendments, defined like this::
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    76
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    77
    odiff=diff --rev 'limit(obsparents(.),1)' --rev .
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    78
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    79
She can see exactly how Bob amended her work.
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    80
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    81
* odiff
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    82
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    83
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    84
Amend ... Stabilize
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    85
--------------------
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    86
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    87
Almost perfect ! Alice just needs to fix a half dozen grammar oddities in
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    88
the new docstrings and it will be publishable.
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    89
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    90
Then, another round of:
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    91
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    92
    $ hg amend
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    93
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    94
and a quick look at hgview ... shows something strange (at first).
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    95
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    96
Ticket #42 yesterday's version is still showing up, with two descendant lineages:
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    97
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    98
* the next version, containing grammar fixes,
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    99
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   100
* the two stacked changesets for tickets #43 .. 44 committed by Bob.
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   101
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   102
Indeed, since this changeset still has non-obsolete descendant
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   103
changesets it cannot be hidden. This branch (old version of #42 and
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   104
the two descendants by C.W.) is said to be _unstable_.
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   105
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   106
Why would one want such a state? Why not auto-stabilize each time "hg
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   107
amend" is typed out?
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   108
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   109
Alice for one, wouldn't want to merge each time she amends something that
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   110
might conflict with the descendant changesets. Remember she is
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   111
currently updating the very middle of an history!
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   112
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   113
Being now done with grammar and typo fixes, Alice decides it is time to
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   114
stabilize again the tree. She does::
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   115
492
7ecd41520dae rename `stabilize` to `evolve`
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 357
diff changeset
   116
    $ hg evolve
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   117
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   118
two times, one for each unstable descendant. The last time, hgview
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   119
shows her a straight line again. Wow! that feels a bit like a
232
adb7e29cb2bd docs: proof-read and review
Benoit Allard <benoit@aeteurope.nl>
parents: 189
diff changeset
   120
well-planned surgical operation. At the end, the patient tree has
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   121
been properly trimmed and any conflict properly handled.
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   122
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   123
Of course nothing fancy really happened: each "stablilize" can be
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   124
understood in terms of a rebase of the next unstable descendant to the
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   125
newest version of its parent (including the possible manual conflict
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   126
resolution intermission ...).
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   127
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   128
Except that rebase is a destructive (it removes information from the
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   129
repository), unrecoverable operation, and the "evolve + obsolete"
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   130
combo, using changeset copy and obsolescence marker, provide evolution
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   131
semantics by only adding new information to the repository (but more
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   132
on that later).
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   133
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   134
She pushes again.
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   135