docs/evolve-collaboration.rst
author Pierre-Yves David <pierre-yves.david@logilab.fr>
Wed, 09 May 2012 16:41:38 +0200
changeset 230 bcf095c8239c
parent 189 e7d7201e79ce
child 232 adb7e29cb2bd
permissions -rw-r--r--
less verbose table
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
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     7
After having written some code for ticket #42, M W. start a patch (this
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     8
will be kind of like a 'work-in-progress' checkpoint initially)::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     9
181
35baa2a80073 docs: fix typos in evolve collaboration.
Arne Babenhauserheide <bab@draketo.de>
parents: 167
diff changeset
    10
    $ hg ci -m '[entities] remove magic'
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    11
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    12
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
    13
in "draft" state.
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
This is easily checkable::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    16
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    17
    $ hg phase tip
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    18
    827: draft
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
See ? Until the day it becomes a "public" changeset, this can be altered
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    21
to no end. How ? It happens with an explicit::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    22
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    23
    $ hg phase -p
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    24
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    25
In practice, pushing to a "publishing" repository can also turn draft
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    26
changesets into public ones. Older mercurial releases are automatically
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    27
"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
    28
(or mutable history).
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    29
181
35baa2a80073 docs: fix typos in evolve collaboration.
Arne Babenhauserheide <bab@draketo.de>
parents: 167
diff changeset
    30
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
    31
happen often, so be careful.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    32
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    33
Now let's come back to our patch. Next hour sees good progress and W.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    34
wants to complete the patch with the recent stuff (all that's shown by
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    35
an "hg diff") to share with a co-worker (let's call him C.W.)::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    36
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    37
    $ hg amend -m '[entities] fix frobulator (closes #42)'
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    38
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    39
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
    40
is just like "hg qrefresh -m").
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
Before leaving, let's push to the central shared repository. That will
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    43
give C.W. the signal that something is ripe for review / further amendments::
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
    $ 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
    46
181
35baa2a80073 docs: fix typos in evolve collaboration.
Arne Babenhauserheide <bab@draketo.de>
parents: 167
diff changeset
    47
The next day, Mr C.W., who arrives very early, can immediately
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    48
work out some glitches in the patch.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    49
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    50
He then starts two other, 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
    51
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
    52
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    53
M W., now equipped with enough properly sugared coffee to survive the
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    54
next two hours::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    55
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    56
    $ hg pull
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    57
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    58
Then::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    59
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    60
    $ hg up "tip ~ 2"
167
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    61
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    62
brings him to yesterday's patch. Indeed the patch serial number has
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    63
increased (827 still exists but has been obsoleted).
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    64
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    65
He understands that his original patch has been altered. But how did it
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    66
evolve ?
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    67
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    68
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
    69
recent version of a patch is shown.
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
Now, when W. installed the mutable-history extensions, he got an alias
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    72
that allows him to see the diff between two amendments, defined like this::
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    73
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    74
    odiff=diff --rev 'limit(obsparents(.),1)' --rev .
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    75
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    76
He can see exactly how C.W. amended his work.
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    77
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    78
* odiff
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    79
64c886d26aab add auc user story
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    80
189
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    81
Amend ... Stabilize
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    82
--------------------
167
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
Almost perfect ! W. just needs to fix a half dozen grammar oddities in
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    85
the new docstrings and it will be publishable.
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    86
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    87
Then, another round of:
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    88
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    89
    $ hg amend
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    90
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    91
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
    92
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    93
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
    94
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    95
* the next version, containing grammar fixes,
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    96
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    97
* the two stacked changesets for tickets #43 .. 44 committed by C.W.
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    98
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
    99
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
   100
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
   101
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
   102
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   103
Why would one want such a state ? Why not auto-stabilize each time "hg
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   104
amend" is spelt ?
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   105
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   106
W. for one, wouldn't want to merge each time he amends something that
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   107
might conflict with the descendant changesets; remember he is
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   108
currently updating the very middle of an history !
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   109
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   110
Being now done with grammar and typo fixes, W. decides it is time to
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   111
stabilize again the tree. He:
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   112
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   113
    $ hg stabilize
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   114
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   115
two times, one for each unstable descendant. The last time, hgview
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   116
shows him a straight line again. Wow ! that feels a bit like a
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   117
well-planned surgical operation. At the end, the patient^Wtree has
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   118
been properly sewed and any conflict properly handled.
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   119
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   120
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
   121
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
   122
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
   123
resolution intermission ...).
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   124
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   125
Except that rebase is a destructive (it removes information from the
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   126
repository), unexchangeable operation, and the "evolve + obsolete"
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   127
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
   128
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
   129
on that later).
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   130
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   131
He pushes again.
e7d7201e79ce follow-up on evolve-collaboration
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 181
diff changeset
   132