annotate docs/evolve-collaboration.rst @ 655:dd5765ae91c3

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.
author Greg Ward <greg@gerg.ca>
date Thu, 24 Jan 2013 18:05:59 -0500
parents b81193ef3488
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
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