docs/evolve-collaboration.rst
author Pierre-Yves.David@ens-lyon.org
Sat, 14 Jul 2012 18:10:24 +0200
branchstable
changeset 362 88cee22c89f1
parent 357 b398e9c2dbd1
child 492 7ecd41520dae
permissions -rw-r--r--
evolve: add the solve alias to obsolete
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     1
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     2
------------------------------------------------
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     3
Collaboration Using Evolve: A user story
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
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     6
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
     7
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
     8
(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
     9
initially)::
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    10
181
35baa2a80073 docs: fix typos in evolve collaboration.
Arne Babenhauserheide <bab@draketo.de>
parents: 167
diff changeset
    11
    $ hg ci -m '[entities] remove magic'
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    12
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    13
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
    14
in "draft" state.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    15
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    16
This is easily checkable::
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
    $ hg phase tip
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    19
    827: draft
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    20
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    21
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
    22
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
    23
232
adb7e29cb2bd docs: proof-read and review
Benoit Allard <benoit@aeteurope.nl>
parents: 189
diff changeset
    24
    $ hg phase --public
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    25
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    26
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
    27
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
    28
"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
    29
(or mutable history).
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    30
181
35baa2a80073 docs: fix typos in evolve collaboration.
Arne Babenhauserheide <bab@draketo.de>
parents: 167
diff changeset
    31
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
    32
happen often, so be careful.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    33
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    34
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
    35
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
    36
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
    37
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    38
    $ hg amend -m '[entities] fix frobulator (closes #42)'
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
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
    41
is just like "hg qrefresh -m").
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    42
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    43
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
    44
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
    45
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    46
    $ 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
    47
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    48
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
    49
some glitches in the patch.
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    50
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    51
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
    52
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
    53
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    54
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
    55
next two hours::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    56
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    57
    $ hg pull
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
Then::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    60
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    61
    $ hg up "tip ~ 2"
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    62
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    63
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
    64
increased (827 still exists but has been obsoleted).
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    65
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    66
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
    67
evolve?
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    68
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    69
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
    70
recent version of a patch is shown.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    71
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    72
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
    73
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
    74
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    75
    odiff=diff --rev 'limit(obsparents(.),1)' --rev .
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    76
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    77
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
    78
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    79
* odiff
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
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    82
Amend ... Stabilize
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    83
--------------------
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    84
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    85
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
    86
the new docstrings and it will be publishable.
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    87
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    88
Then, another round of:
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
    $ hg amend
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
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
    93
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    94
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
    95
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    96
* the next version, containing grammar fixes,
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    97
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
    98
* 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
    99
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   100
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
   101
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
   102
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
   103
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   104
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
   105
amend" is typed out?
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   106
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   107
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
   108
might conflict with the descendant changesets. Remember she is
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   109
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
   110
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   111
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
   112
stabilize again the tree. She does::
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   113
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   114
    $ hg stabilize
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   115
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   116
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
   117
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
   118
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
   119
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
   120
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   121
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
   122
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
   123
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
   124
resolution intermission ...).
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   125
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   126
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
   127
repository), unrecoverable operation, and the "evolve + obsolete"
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   128
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
   129
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
   130
on that later).
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   131
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 232
diff changeset
   132
She pushes again.
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   133