docs/evolve-collaboration.rst
author Greg Ward <greg@gerg.ca>
Thu, 24 Jan 2013 18:05:59 -0500
changeset 655 dd5765ae91c3
parent 527 b81193ef3488
permissions -rw-r--r--
doc: fix grammar, spelling, punctuation I restrained myself to making only changes that turn bad English into good English. There are still opportunities to improve, but other changes require some discussion and review. This change should be uncontroversial.
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
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 527
diff changeset
    15
Instant patch! Note how the default phase of this changeset is (still)
167
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
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 527
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
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 527
diff changeset
    42
Note that we also fix the commit message. (For recovering MQ users: this
167
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
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 527
diff changeset
    68
She understands that her original patch has been altered. But how did it
357
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
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 527
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"
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 527
diff changeset
   130
combo, using changeset copy and obsolescence marker, provides evolution
189
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