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