Mercurial > hgbook
comparison en/ch12-mq-collab.xml @ 683:c838b3975bc6
Add IDs to paragraphs.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu, 19 Mar 2009 21:18:52 -0700 |
parents | 28b5a5befb08 |
children | 4ce9d0754af3 |
comparison
equal
deleted
inserted
replaced
682:28b5a5befb08 | 683:c838b3975bc6 |
---|---|
2 | 2 |
3 <chapter id="chap:mq-collab"> | 3 <chapter id="chap:mq-collab"> |
4 <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?> | 4 <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?> |
5 <title>Advanced uses of Mercurial Queues</title> | 5 <title>Advanced uses of Mercurial Queues</title> |
6 | 6 |
7 <para>While it's easy to pick up straightforward uses of Mercurial | 7 <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial |
8 Queues, use of a little discipline and some of MQ's less | 8 Queues, use of a little discipline and some of MQ's less |
9 frequently used capabilities makes it possible to work in | 9 frequently used capabilities makes it possible to work in |
10 complicated development environments.</para> | 10 complicated development environments.</para> |
11 | 11 |
12 <para>In this chapter, I will use as an example a technique I have | 12 <para id="x_15e">In this chapter, I will use as an example a technique I have |
13 used to manage the development of an Infiniband device driver for | 13 used to manage the development of an Infiniband device driver for |
14 the Linux kernel. The driver in question is large (at least as | 14 the Linux kernel. The driver in question is large (at least as |
15 drivers go), with 25,000 lines of code spread across 35 source | 15 drivers go), with 25,000 lines of code spread across 35 source |
16 files. It is maintained by a small team of developers.</para> | 16 files. It is maintained by a small team of developers.</para> |
17 | 17 |
18 <para>While much of the material in this chapter is specific to | 18 <para id="x_15f">While much of the material in this chapter is specific to |
19 Linux, the same principles apply to any code base for which you're | 19 Linux, the same principles apply to any code base for which you're |
20 not the primary owner, and upon which you need to do a lot of | 20 not the primary owner, and upon which you need to do a lot of |
21 development.</para> | 21 development.</para> |
22 | 22 |
23 <sect1> | 23 <sect1> |
24 <title>The problem of many targets</title> | 24 <title>The problem of many targets</title> |
25 | 25 |
26 <para>The Linux kernel changes rapidly, and has never been | 26 <para id="x_160">The Linux kernel changes rapidly, and has never been |
27 internally stable; developers frequently make drastic changes | 27 internally stable; developers frequently make drastic changes |
28 between releases. This means that a version of the driver that | 28 between releases. This means that a version of the driver that |
29 works well with a particular released version of the kernel will | 29 works well with a particular released version of the kernel will |
30 not even <emphasis>compile</emphasis> correctly against, | 30 not even <emphasis>compile</emphasis> correctly against, |
31 typically, any other version.</para> | 31 typically, any other version.</para> |
32 | 32 |
33 <para>To maintain a driver, we have to keep a number of distinct | 33 <para id="x_161">To maintain a driver, we have to keep a number of distinct |
34 versions of Linux in mind.</para> | 34 versions of Linux in mind.</para> |
35 <itemizedlist> | 35 <itemizedlist> |
36 <listitem><para>One target is the main Linux kernel development | 36 <listitem><para id="x_162">One target is the main Linux kernel development |
37 tree. Maintenance of the code is in this case partly shared | 37 tree. Maintenance of the code is in this case partly shared |
38 by other developers in the kernel community, who make | 38 by other developers in the kernel community, who make |
39 <quote>drive-by</quote> modifications to the driver as they | 39 <quote>drive-by</quote> modifications to the driver as they |
40 develop and refine kernel subsystems.</para> | 40 develop and refine kernel subsystems.</para> |
41 </listitem> | 41 </listitem> |
42 <listitem><para>We also maintain a number of | 42 <listitem><para id="x_163">We also maintain a number of |
43 <quote>backports</quote> to older versions of the Linux | 43 <quote>backports</quote> to older versions of the Linux |
44 kernel, to support the needs of customers who are running | 44 kernel, to support the needs of customers who are running |
45 older Linux distributions that do not incorporate our | 45 older Linux distributions that do not incorporate our |
46 drivers. (To <emphasis>backport</emphasis> a piece of code | 46 drivers. (To <emphasis>backport</emphasis> a piece of code |
47 is to modify it to work in an older version of its target | 47 is to modify it to work in an older version of its target |
48 environment than the version it was developed for.)</para> | 48 environment than the version it was developed for.)</para> |
49 </listitem> | 49 </listitem> |
50 <listitem><para>Finally, we make software releases on a schedule | 50 <listitem><para id="x_164">Finally, we make software releases on a schedule |
51 that is necessarily not aligned with those used by Linux | 51 that is necessarily not aligned with those used by Linux |
52 distributors and kernel developers, so that we can deliver | 52 distributors and kernel developers, so that we can deliver |
53 new features to customers without forcing them to upgrade | 53 new features to customers without forcing them to upgrade |
54 their entire kernels or distributions.</para> | 54 their entire kernels or distributions.</para> |
55 </listitem></itemizedlist> | 55 </listitem></itemizedlist> |
56 | 56 |
57 <sect2> | 57 <sect2> |
58 <title>Tempting approaches that don't work well</title> | 58 <title>Tempting approaches that don't work well</title> |
59 | 59 |
60 <para>There are two <quote>standard</quote> ways to maintain a | 60 <para id="x_165">There are two <quote>standard</quote> ways to maintain a |
61 piece of software that has to target many different | 61 piece of software that has to target many different |
62 environments.</para> | 62 environments.</para> |
63 | 63 |
64 <para>The first is to maintain a number of branches, each | 64 <para id="x_166">The first is to maintain a number of branches, each |
65 intended for a single target. The trouble with this approach | 65 intended for a single target. The trouble with this approach |
66 is that you must maintain iron discipline in the flow of | 66 is that you must maintain iron discipline in the flow of |
67 changes between repositories. A new feature or bug fix must | 67 changes between repositories. A new feature or bug fix must |
68 start life in a <quote>pristine</quote> repository, then | 68 start life in a <quote>pristine</quote> repository, then |
69 percolate out to every backport repository. Backport changes | 69 percolate out to every backport repository. Backport changes |
70 are more limited in the branches they should propagate to; a | 70 are more limited in the branches they should propagate to; a |
71 backport change that is applied to a branch where it doesn't | 71 backport change that is applied to a branch where it doesn't |
72 belong will probably stop the driver from compiling.</para> | 72 belong will probably stop the driver from compiling.</para> |
73 | 73 |
74 <para>The second is to maintain a single source tree filled with | 74 <para id="x_167">The second is to maintain a single source tree filled with |
75 conditional statements that turn chunks of code on or off | 75 conditional statements that turn chunks of code on or off |
76 depending on the intended target. Because these | 76 depending on the intended target. Because these |
77 <quote>ifdefs</quote> are not allowed in the Linux kernel | 77 <quote>ifdefs</quote> are not allowed in the Linux kernel |
78 tree, a manual or automatic process must be followed to strip | 78 tree, a manual or automatic process must be followed to strip |
79 them out and yield a clean tree. A code base maintained in | 79 them out and yield a clean tree. A code base maintained in |
80 this fashion rapidly becomes a rat's nest of conditional | 80 this fashion rapidly becomes a rat's nest of conditional |
81 blocks that are difficult to understand and maintain.</para> | 81 blocks that are difficult to understand and maintain.</para> |
82 | 82 |
83 <para>Neither of these approaches is well suited to a situation | 83 <para id="x_168">Neither of these approaches is well suited to a situation |
84 where you don't <quote>own</quote> the canonical copy of a | 84 where you don't <quote>own</quote> the canonical copy of a |
85 source tree. In the case of a Linux driver that is | 85 source tree. In the case of a Linux driver that is |
86 distributed with the standard kernel, Linus's tree contains | 86 distributed with the standard kernel, Linus's tree contains |
87 the copy of the code that will be treated by the world as | 87 the copy of the code that will be treated by the world as |
88 canonical. The upstream version of <quote>my</quote> driver | 88 canonical. The upstream version of <quote>my</quote> driver |
89 can be modified by people I don't know, without me even | 89 can be modified by people I don't know, without me even |
90 finding out about it until after the changes show up in | 90 finding out about it until after the changes show up in |
91 Linus's tree.</para> | 91 Linus's tree.</para> |
92 | 92 |
93 <para>These approaches have the added weakness of making it | 93 <para id="x_169">These approaches have the added weakness of making it |
94 difficult to generate well-formed patches to submit | 94 difficult to generate well-formed patches to submit |
95 upstream.</para> | 95 upstream.</para> |
96 | 96 |
97 <para>In principle, Mercurial Queues seems like a good candidate | 97 <para id="x_16a">In principle, Mercurial Queues seems like a good candidate |
98 to manage a development scenario such as the above. While | 98 to manage a development scenario such as the above. While |
99 this is indeed the case, MQ contains a few added features that | 99 this is indeed the case, MQ contains a few added features that |
100 make the job more pleasant.</para> | 100 make the job more pleasant.</para> |
101 | 101 |
102 </sect2> | 102 </sect2> |
103 </sect1> | 103 </sect1> |
104 <sect1> | 104 <sect1> |
105 <title>Conditionally applying patches with guards</title> | 105 <title>Conditionally applying patches with guards</title> |
106 | 106 |
107 <para>Perhaps the best way to maintain sanity with so many targets | 107 <para id="x_16b">Perhaps the best way to maintain sanity with so many targets |
108 is to be able to choose specific patches to apply for a given | 108 is to be able to choose specific patches to apply for a given |
109 situation. MQ provides a feature called <quote>guards</quote> | 109 situation. MQ provides a feature called <quote>guards</quote> |
110 (which originates with quilt's <literal>guards</literal> | 110 (which originates with quilt's <literal>guards</literal> |
111 command) that does just this. To start off, let's create a | 111 command) that does just this. To start off, let's create a |
112 simple repository for experimenting in.</para> | 112 simple repository for experimenting in.</para> |
113 | 113 |
114 &interaction.mq.guards.init; | 114 &interaction.mq.guards.init; |
115 | 115 |
116 <para>This gives us a tiny repository that contains two patches | 116 <para id="x_16c">This gives us a tiny repository that contains two patches |
117 that don't have any dependencies on each other, because they | 117 that don't have any dependencies on each other, because they |
118 touch different files.</para> | 118 touch different files.</para> |
119 | 119 |
120 <para>The idea behind conditional application is that you can | 120 <para id="x_16d">The idea behind conditional application is that you can |
121 <quote>tag</quote> a patch with a <emphasis>guard</emphasis>, | 121 <quote>tag</quote> a patch with a <emphasis>guard</emphasis>, |
122 which is simply a text string of your choosing, then tell MQ to | 122 which is simply a text string of your choosing, then tell MQ to |
123 select specific guards to use when applying patches. MQ will | 123 select specific guards to use when applying patches. MQ will |
124 then either apply, or skip over, a guarded patch, depending on | 124 then either apply, or skip over, a guarded patch, depending on |
125 the guards that you have selected.</para> | 125 the guards that you have selected.</para> |
126 | 126 |
127 <para>A patch can have an arbitrary number of guards; each one is | 127 <para id="x_16e">A patch can have an arbitrary number of guards; each one is |
128 <emphasis>positive</emphasis> (<quote>apply this patch if this | 128 <emphasis>positive</emphasis> (<quote>apply this patch if this |
129 guard is selected</quote>) or <emphasis>negative</emphasis> | 129 guard is selected</quote>) or <emphasis>negative</emphasis> |
130 (<quote>skip this patch if this guard is selected</quote>). A | 130 (<quote>skip this patch if this guard is selected</quote>). A |
131 patch with no guards is always applied.</para> | 131 patch with no guards is always applied.</para> |
132 | 132 |
133 </sect1> | 133 </sect1> |
134 <sect1> | 134 <sect1> |
135 <title>Controlling the guards on a patch</title> | 135 <title>Controlling the guards on a patch</title> |
136 | 136 |
137 <para>The <command role="hg-ext-mq">qguard</command> command lets | 137 <para id="x_16f">The <command role="hg-ext-mq">qguard</command> command lets |
138 you determine which guards should apply to a patch, or display | 138 you determine which guards should apply to a patch, or display |
139 the guards that are already in effect. Without any arguments, it | 139 the guards that are already in effect. Without any arguments, it |
140 displays the guards on the current topmost patch.</para> | 140 displays the guards on the current topmost patch.</para> |
141 | 141 |
142 &interaction.mq.guards.qguard; | 142 &interaction.mq.guards.qguard; |
143 | 143 |
144 <para>To set a positive guard on a patch, prefix the name of the | 144 <para id="x_170">To set a positive guard on a patch, prefix the name of the |
145 guard with a <quote><literal>+</literal></quote>.</para> | 145 guard with a <quote><literal>+</literal></quote>.</para> |
146 | 146 |
147 &interaction.mq.guards.qguard.pos; | 147 &interaction.mq.guards.qguard.pos; |
148 | 148 |
149 <para>To set a negative guard | 149 <para id="x_171">To set a negative guard |
150 on a patch, prefix the name of the guard with a | 150 on a patch, prefix the name of the guard with a |
151 <quote><literal>-</literal></quote>.</para> | 151 <quote><literal>-</literal></quote>.</para> |
152 | 152 |
153 &interaction.mq.guards.qguard.neg; | 153 &interaction.mq.guards.qguard.neg; |
154 | 154 |
155 <note> | 155 <note> |
156 <para> The <command role="hg-ext-mq">qguard</command> command | 156 <para id="x_172"> The <command role="hg-ext-mq">qguard</command> command |
157 <emphasis>sets</emphasis> the guards on a patch; it doesn't | 157 <emphasis>sets</emphasis> the guards on a patch; it doesn't |
158 <emphasis>modify</emphasis> them. What this means is that if | 158 <emphasis>modify</emphasis> them. What this means is that if |
159 you run <command role="hg-cmd">hg qguard +a +b</command> on a | 159 you run <command role="hg-cmd">hg qguard +a +b</command> on a |
160 patch, then <command role="hg-cmd">hg qguard +c</command> on | 160 patch, then <command role="hg-cmd">hg qguard +c</command> on |
161 the same patch, the <emphasis>only</emphasis> guard that will | 161 the same patch, the <emphasis>only</emphasis> guard that will |
162 be set on it afterwards is <literal>+c</literal>.</para> | 162 be set on it afterwards is <literal>+c</literal>.</para> |
163 </note> | 163 </note> |
164 | 164 |
165 <para>Mercurial stores guards in the <filename | 165 <para id="x_173">Mercurial stores guards in the <filename |
166 role="special">series</filename> file; the form in which they | 166 role="special">series</filename> file; the form in which they |
167 are stored is easy both to understand and to edit by hand. (In | 167 are stored is easy both to understand and to edit by hand. (In |
168 other words, you don't have to use the <command | 168 other words, you don't have to use the <command |
169 role="hg-ext-mq">qguard</command> command if you don't want | 169 role="hg-ext-mq">qguard</command> command if you don't want |
170 to; it's okay to simply edit the <filename | 170 to; it's okay to simply edit the <filename |
174 | 174 |
175 </sect1> | 175 </sect1> |
176 <sect1> | 176 <sect1> |
177 <title>Selecting the guards to use</title> | 177 <title>Selecting the guards to use</title> |
178 | 178 |
179 <para>The <command role="hg-ext-mq">qselect</command> command | 179 <para id="x_174">The <command role="hg-ext-mq">qselect</command> command |
180 determines which guards are active at a given time. The effect | 180 determines which guards are active at a given time. The effect |
181 of this is to determine which patches MQ will apply the next | 181 of this is to determine which patches MQ will apply the next |
182 time you run <command role="hg-ext-mq">qpush</command>. It has | 182 time you run <command role="hg-ext-mq">qpush</command>. It has |
183 no other effect; in particular, it doesn't do anything to | 183 no other effect; in particular, it doesn't do anything to |
184 patches that are already applied.</para> | 184 patches that are already applied.</para> |
185 | 185 |
186 <para>With no arguments, the <command | 186 <para id="x_175">With no arguments, the <command |
187 role="hg-ext-mq">qselect</command> command lists the guards | 187 role="hg-ext-mq">qselect</command> command lists the guards |
188 currently in effect, one per line of output. Each argument is | 188 currently in effect, one per line of output. Each argument is |
189 treated as the name of a guard to apply.</para> | 189 treated as the name of a guard to apply.</para> |
190 | 190 |
191 &interaction.mq.guards.qselect.foo; | 191 &interaction.mq.guards.qselect.foo; |
192 | 192 |
193 <para>In case you're interested, the currently selected guards are | 193 <para id="x_176">In case you're interested, the currently selected guards are |
194 stored in the <filename role="special">guards</filename> file.</para> | 194 stored in the <filename role="special">guards</filename> file.</para> |
195 | 195 |
196 &interaction.mq.guards.qselect.cat; | 196 &interaction.mq.guards.qselect.cat; |
197 | 197 |
198 <para>We can see the effect the selected guards have when we run | 198 <para id="x_177">We can see the effect the selected guards have when we run |
199 <command role="hg-ext-mq">qpush</command>.</para> | 199 <command role="hg-ext-mq">qpush</command>.</para> |
200 | 200 |
201 &interaction.mq.guards.qselect.qpush; | 201 &interaction.mq.guards.qselect.qpush; |
202 | 202 |
203 <para>A guard cannot start with a | 203 <para id="x_178">A guard cannot start with a |
204 <quote><literal>+</literal></quote> or | 204 <quote><literal>+</literal></quote> or |
205 <quote><literal>-</literal></quote> character. The name of a | 205 <quote><literal>-</literal></quote> character. The name of a |
206 guard must not contain white space, but most other characters | 206 guard must not contain white space, but most other characters |
207 are acceptable. If you try to use a guard with an invalid name, | 207 are acceptable. If you try to use a guard with an invalid name, |
208 MQ will complain:</para> | 208 MQ will complain:</para> |
209 | 209 |
210 &interaction.mq.guards.qselect.error; | 210 &interaction.mq.guards.qselect.error; |
211 | 211 |
212 <para>Changing the selected guards changes the patches that are | 212 <para id="x_179">Changing the selected guards changes the patches that are |
213 applied.</para> | 213 applied.</para> |
214 | 214 |
215 &interaction.mq.guards.qselect.quux; | 215 &interaction.mq.guards.qselect.quux; |
216 | 216 |
217 <para>You can see in the example below that negative guards take | 217 <para id="x_17a">You can see in the example below that negative guards take |
218 precedence over positive guards.</para> | 218 precedence over positive guards.</para> |
219 | 219 |
220 &interaction.mq.guards.qselect.foobar; | 220 &interaction.mq.guards.qselect.foobar; |
221 | 221 |
222 </sect1> | 222 </sect1> |
223 <sect1> | 223 <sect1> |
224 <title>MQ's rules for applying patches</title> | 224 <title>MQ's rules for applying patches</title> |
225 | 225 |
226 <para>The rules that MQ uses when deciding whether to apply a | 226 <para id="x_17b">The rules that MQ uses when deciding whether to apply a |
227 patch are as follows.</para> | 227 patch are as follows.</para> |
228 <itemizedlist> | 228 <itemizedlist> |
229 <listitem><para>A patch that has no guards is always | 229 <listitem><para id="x_17c">A patch that has no guards is always |
230 applied.</para> | 230 applied.</para> |
231 </listitem> | 231 </listitem> |
232 <listitem><para>If the patch has any negative guard that matches | 232 <listitem><para id="x_17d">If the patch has any negative guard that matches |
233 any currently selected guard, the patch is skipped.</para> | 233 any currently selected guard, the patch is skipped.</para> |
234 </listitem> | 234 </listitem> |
235 <listitem><para>If the patch has any positive guard that matches | 235 <listitem><para id="x_17e">If the patch has any positive guard that matches |
236 any currently selected guard, the patch is applied.</para> | 236 any currently selected guard, the patch is applied.</para> |
237 </listitem> | 237 </listitem> |
238 <listitem><para>If the patch has positive or negative guards, | 238 <listitem><para id="x_17f">If the patch has positive or negative guards, |
239 but none matches any currently selected guard, the patch is | 239 but none matches any currently selected guard, the patch is |
240 skipped.</para> | 240 skipped.</para> |
241 </listitem></itemizedlist> | 241 </listitem></itemizedlist> |
242 | 242 |
243 </sect1> | 243 </sect1> |
244 <sect1> | 244 <sect1> |
245 <title>Trimming the work environment</title> | 245 <title>Trimming the work environment</title> |
246 | 246 |
247 <para>In working on the device driver I mentioned earlier, I don't | 247 <para id="x_180">In working on the device driver I mentioned earlier, I don't |
248 apply the patches to a normal Linux kernel tree. Instead, I use | 248 apply the patches to a normal Linux kernel tree. Instead, I use |
249 a repository that contains only a snapshot of the source files | 249 a repository that contains only a snapshot of the source files |
250 and headers that are relevant to Infiniband development. This | 250 and headers that are relevant to Infiniband development. This |
251 repository is 1% the size of a kernel repository, so it's easier | 251 repository is 1% the size of a kernel repository, so it's easier |
252 to work with.</para> | 252 to work with.</para> |
253 | 253 |
254 <para>I then choose a <quote>base</quote> version on top of which | 254 <para id="x_181">I then choose a <quote>base</quote> version on top of which |
255 the patches are applied. This is a snapshot of the Linux kernel | 255 the patches are applied. This is a snapshot of the Linux kernel |
256 tree as of a revision of my choosing. When I take the snapshot, | 256 tree as of a revision of my choosing. When I take the snapshot, |
257 I record the changeset ID from the kernel repository in the | 257 I record the changeset ID from the kernel repository in the |
258 commit message. Since the snapshot preserves the | 258 commit message. Since the snapshot preserves the |
259 <quote>shape</quote> and content of the relevant parts of the | 259 <quote>shape</quote> and content of the relevant parts of the |
260 kernel tree, I can apply my patches on top of either my tiny | 260 kernel tree, I can apply my patches on top of either my tiny |
261 repository or a normal kernel tree.</para> | 261 repository or a normal kernel tree.</para> |
262 | 262 |
263 <para>Normally, the base tree atop which the patches apply should | 263 <para id="x_182">Normally, the base tree atop which the patches apply should |
264 be a snapshot of a very recent upstream tree. This best | 264 be a snapshot of a very recent upstream tree. This best |
265 facilitates the development of patches that can easily be | 265 facilitates the development of patches that can easily be |
266 submitted upstream with few or no modifications.</para> | 266 submitted upstream with few or no modifications.</para> |
267 | 267 |
268 </sect1> | 268 </sect1> |
269 <sect1> | 269 <sect1> |
270 <title>Dividing up the <filename role="special">series</filename> | 270 <title>Dividing up the <filename role="special">series</filename> |
271 file</title> | 271 file</title> |
272 | 272 |
273 <para>I categorise the patches in the <filename | 273 <para id="x_183">I categorise the patches in the <filename |
274 role="special">series</filename> file into a number of logical | 274 role="special">series</filename> file into a number of logical |
275 groups. Each section of like patches begins with a block of | 275 groups. Each section of like patches begins with a block of |
276 comments that describes the purpose of the patches that | 276 comments that describes the purpose of the patches that |
277 follow.</para> | 277 follow.</para> |
278 | 278 |
279 <para>The sequence of patch groups that I maintain follows. The | 279 <para id="x_184">The sequence of patch groups that I maintain follows. The |
280 ordering of these groups is important; I'll describe why after I | 280 ordering of these groups is important; I'll describe why after I |
281 introduce the groups.</para> | 281 introduce the groups.</para> |
282 <itemizedlist> | 282 <itemizedlist> |
283 <listitem><para>The <quote>accepted</quote> group. Patches that | 283 <listitem><para id="x_185">The <quote>accepted</quote> group. Patches that |
284 the development team has submitted to the maintainer of the | 284 the development team has submitted to the maintainer of the |
285 Infiniband subsystem, and which he has accepted, but which | 285 Infiniband subsystem, and which he has accepted, but which |
286 are not present in the snapshot that the tiny repository is | 286 are not present in the snapshot that the tiny repository is |
287 based on. These are <quote>read only</quote> patches, | 287 based on. These are <quote>read only</quote> patches, |
288 present only to transform the tree into a similar state as | 288 present only to transform the tree into a similar state as |
289 it is in the upstream maintainer's repository.</para> | 289 it is in the upstream maintainer's repository.</para> |
290 </listitem> | 290 </listitem> |
291 <listitem><para>The <quote>rework</quote> group. Patches that I | 291 <listitem><para id="x_186">The <quote>rework</quote> group. Patches that I |
292 have submitted, but that the upstream maintainer has | 292 have submitted, but that the upstream maintainer has |
293 requested modifications to before he will accept | 293 requested modifications to before he will accept |
294 them.</para> | 294 them.</para> |
295 </listitem> | 295 </listitem> |
296 <listitem><para>The <quote>pending</quote> group. Patches that | 296 <listitem><para id="x_187">The <quote>pending</quote> group. Patches that |
297 I have not yet submitted to the upstream maintainer, but | 297 I have not yet submitted to the upstream maintainer, but |
298 which we have finished working on. These will be <quote>read | 298 which we have finished working on. These will be <quote>read |
299 only</quote> for a while. If the upstream maintainer | 299 only</quote> for a while. If the upstream maintainer |
300 accepts them upon submission, I'll move them to the end of | 300 accepts them upon submission, I'll move them to the end of |
301 the <quote>accepted</quote> group. If he requests that I | 301 the <quote>accepted</quote> group. If he requests that I |
302 modify any, I'll move them to the beginning of the | 302 modify any, I'll move them to the beginning of the |
303 <quote>rework</quote> group.</para> | 303 <quote>rework</quote> group.</para> |
304 </listitem> | 304 </listitem> |
305 <listitem><para>The <quote>in progress</quote> group. Patches | 305 <listitem><para id="x_188">The <quote>in progress</quote> group. Patches |
306 that are actively being developed, and should not be | 306 that are actively being developed, and should not be |
307 submitted anywhere yet.</para> | 307 submitted anywhere yet.</para> |
308 </listitem> | 308 </listitem> |
309 <listitem><para>The <quote>backport</quote> group. Patches that | 309 <listitem><para id="x_189">The <quote>backport</quote> group. Patches that |
310 adapt the source tree to older versions of the kernel | 310 adapt the source tree to older versions of the kernel |
311 tree.</para> | 311 tree.</para> |
312 </listitem> | 312 </listitem> |
313 <listitem><para>The <quote>do not ship</quote> group. Patches | 313 <listitem><para id="x_18a">The <quote>do not ship</quote> group. Patches |
314 that for some reason should never be submitted upstream. | 314 that for some reason should never be submitted upstream. |
315 For example, one such patch might change embedded driver | 315 For example, one such patch might change embedded driver |
316 identification strings to make it easier to distinguish, in | 316 identification strings to make it easier to distinguish, in |
317 the field, between an out-of-tree version of the driver and | 317 the field, between an out-of-tree version of the driver and |
318 a version shipped by a distribution vendor.</para> | 318 a version shipped by a distribution vendor.</para> |
319 </listitem></itemizedlist> | 319 </listitem></itemizedlist> |
320 | 320 |
321 <para>Now to return to the reasons for ordering groups of patches | 321 <para id="x_18b">Now to return to the reasons for ordering groups of patches |
322 in this way. We would like the lowest patches in the stack to | 322 in this way. We would like the lowest patches in the stack to |
323 be as stable as possible, so that we will not need to rework | 323 be as stable as possible, so that we will not need to rework |
324 higher patches due to changes in context. Putting patches that | 324 higher patches due to changes in context. Putting patches that |
325 will never be changed first in the <filename | 325 will never be changed first in the <filename |
326 role="special">series</filename> file serves this | 326 role="special">series</filename> file serves this |
327 purpose.</para> | 327 purpose.</para> |
328 | 328 |
329 <para>We would also like the patches that we know we'll need to | 329 <para id="x_18c">We would also like the patches that we know we'll need to |
330 modify to be applied on top of a source tree that resembles the | 330 modify to be applied on top of a source tree that resembles the |
331 upstream tree as closely as possible. This is why we keep | 331 upstream tree as closely as possible. This is why we keep |
332 accepted patches around for a while.</para> | 332 accepted patches around for a while.</para> |
333 | 333 |
334 <para>The <quote>backport</quote> and <quote>do not ship</quote> | 334 <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote> |
335 patches float at the end of the <filename | 335 patches float at the end of the <filename |
336 role="special">series</filename> file. The backport patches | 336 role="special">series</filename> file. The backport patches |
337 must be applied on top of all other patches, and the <quote>do | 337 must be applied on top of all other patches, and the <quote>do |
338 not ship</quote> patches might as well stay out of harm's | 338 not ship</quote> patches might as well stay out of harm's |
339 way.</para> | 339 way.</para> |
340 | 340 |
341 </sect1> | 341 </sect1> |
342 <sect1> | 342 <sect1> |
343 <title>Maintaining the patch series</title> | 343 <title>Maintaining the patch series</title> |
344 | 344 |
345 <para>In my work, I use a number of guards to control which | 345 <para id="x_18e">In my work, I use a number of guards to control which |
346 patches are to be applied.</para> | 346 patches are to be applied.</para> |
347 | 347 |
348 <itemizedlist> | 348 <itemizedlist> |
349 <listitem><para><quote>Accepted</quote> patches are guarded with | 349 <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with |
350 <literal>accepted</literal>. I enable this guard most of | 350 <literal>accepted</literal>. I enable this guard most of |
351 the time. When I'm applying the patches on top of a tree | 351 the time. When I'm applying the patches on top of a tree |
352 where the patches are already present, I can turn this patch | 352 where the patches are already present, I can turn this patch |
353 off, and the patches that follow it will apply | 353 off, and the patches that follow it will apply |
354 cleanly.</para> | 354 cleanly.</para> |
355 </listitem> | 355 </listitem> |
356 <listitem><para>Patches that are <quote>finished</quote>, but | 356 <listitem><para id="x_190">Patches that are <quote>finished</quote>, but |
357 not yet submitted, have no guards. If I'm applying the | 357 not yet submitted, have no guards. If I'm applying the |
358 patch stack to a copy of the upstream tree, I don't need to | 358 patch stack to a copy of the upstream tree, I don't need to |
359 enable any guards in order to get a reasonably safe source | 359 enable any guards in order to get a reasonably safe source |
360 tree.</para> | 360 tree.</para> |
361 </listitem> | 361 </listitem> |
362 <listitem><para>Those patches that need reworking before being | 362 <listitem><para id="x_191">Those patches that need reworking before being |
363 resubmitted are guarded with | 363 resubmitted are guarded with |
364 <literal>rework</literal>.</para> | 364 <literal>rework</literal>.</para> |
365 </listitem> | 365 </listitem> |
366 <listitem><para>For those patches that are still under | 366 <listitem><para id="x_192">For those patches that are still under |
367 development, I use <literal>devel</literal>.</para> | 367 development, I use <literal>devel</literal>.</para> |
368 </listitem> | 368 </listitem> |
369 <listitem><para>A backport patch may have several guards, one | 369 <listitem><para id="x_193">A backport patch may have several guards, one |
370 for each version of the kernel to which it applies. For | 370 for each version of the kernel to which it applies. For |
371 example, a patch that backports a piece of code to 2.6.9 | 371 example, a patch that backports a piece of code to 2.6.9 |
372 will have a <literal>2.6.9</literal> guard.</para> | 372 will have a <literal>2.6.9</literal> guard.</para> |
373 </listitem></itemizedlist> | 373 </listitem></itemizedlist> |
374 <para>This variety of guards gives me considerable flexibility in | 374 <para id="x_194">This variety of guards gives me considerable flexibility in |
375 determining what kind of source tree I want to end up with. For | 375 determining what kind of source tree I want to end up with. For |
376 most situations, the selection of appropriate guards is | 376 most situations, the selection of appropriate guards is |
377 automated during the build process, but I can manually tune the | 377 automated during the build process, but I can manually tune the |
378 guards to use for less common circumstances.</para> | 378 guards to use for less common circumstances.</para> |
379 | 379 |
380 <sect2> | 380 <sect2> |
381 <title>The art of writing backport patches</title> | 381 <title>The art of writing backport patches</title> |
382 | 382 |
383 <para>Using MQ, writing a backport patch is a simple process. | 383 <para id="x_195">Using MQ, writing a backport patch is a simple process. |
384 All such a patch has to do is modify a piece of code that uses | 384 All such a patch has to do is modify a piece of code that uses |
385 a kernel feature not present in the older version of the | 385 a kernel feature not present in the older version of the |
386 kernel, so that the driver continues to work correctly under | 386 kernel, so that the driver continues to work correctly under |
387 that older version.</para> | 387 that older version.</para> |
388 | 388 |
389 <para>A useful goal when writing a good backport patch is to | 389 <para id="x_196">A useful goal when writing a good backport patch is to |
390 make your code look as if it was written for the older version | 390 make your code look as if it was written for the older version |
391 of the kernel you're targeting. The less obtrusive the patch, | 391 of the kernel you're targeting. The less obtrusive the patch, |
392 the easier it will be to understand and maintain. If you're | 392 the easier it will be to understand and maintain. If you're |
393 writing a collection of backport patches to avoid the | 393 writing a collection of backport patches to avoid the |
394 <quote>rat's nest</quote> effect of lots of | 394 <quote>rat's nest</quote> effect of lots of |
397 version-dependent <literal>#ifdef</literal>s into the patches. | 397 version-dependent <literal>#ifdef</literal>s into the patches. |
398 Instead, write several patches, each of which makes | 398 Instead, write several patches, each of which makes |
399 unconditional changes, and control their application using | 399 unconditional changes, and control their application using |
400 guards.</para> | 400 guards.</para> |
401 | 401 |
402 <para>There are two reasons to divide backport patches into a | 402 <para id="x_197">There are two reasons to divide backport patches into a |
403 distinct group, away from the <quote>regular</quote> patches | 403 distinct group, away from the <quote>regular</quote> patches |
404 whose effects they modify. The first is that intermingling the | 404 whose effects they modify. The first is that intermingling the |
405 two makes it more difficult to use a tool like the <literal | 405 two makes it more difficult to use a tool like the <literal |
406 role="hg-ext">patchbomb</literal> extension to automate the | 406 role="hg-ext">patchbomb</literal> extension to automate the |
407 process of submitting the patches to an upstream maintainer. | 407 process of submitting the patches to an upstream maintainer. |
417 <title>Useful tips for developing with MQ</title> | 417 <title>Useful tips for developing with MQ</title> |
418 | 418 |
419 <sect2> | 419 <sect2> |
420 <title>Organising patches in directories</title> | 420 <title>Organising patches in directories</title> |
421 | 421 |
422 <para>If you're working on a substantial project with MQ, it's | 422 <para id="x_198">If you're working on a substantial project with MQ, it's |
423 not difficult to accumulate a large number of patches. For | 423 not difficult to accumulate a large number of patches. For |
424 example, I have one patch repository that contains over 250 | 424 example, I have one patch repository that contains over 250 |
425 patches.</para> | 425 patches.</para> |
426 | 426 |
427 <para>If you can group these patches into separate logical | 427 <para id="x_199">If you can group these patches into separate logical |
428 categories, you can if you like store them in different | 428 categories, you can if you like store them in different |
429 directories; MQ has no problems with patch names that contain | 429 directories; MQ has no problems with patch names that contain |
430 path separators.</para> | 430 path separators.</para> |
431 | 431 |
432 </sect2> | 432 </sect2> |
433 <sect2 id="mq-collab:tips:interdiff"> | 433 <sect2 id="mq-collab:tips:interdiff"> |
434 <title>Viewing the history of a patch</title> | 434 <title>Viewing the history of a patch</title> |
435 | 435 |
436 <para>If you're developing a set of patches over a long time, | 436 <para id="x_19a">If you're developing a set of patches over a long time, |
437 it's a good idea to maintain them in a repository, as | 437 it's a good idea to maintain them in a repository, as |
438 discussed in section <xref linkend="sec:mq:repo"/>. If you do | 438 discussed in section <xref linkend="sec:mq:repo"/>. If you do |
439 so, you'll quickly | 439 so, you'll quickly |
440 discover that using the <command role="hg-cmd">hg | 440 discover that using the <command role="hg-cmd">hg |
441 diff</command> command to look at the history of changes to | 441 diff</command> command to look at the history of changes to |
443 at the second derivative of the real code (a diff of a diff), | 443 at the second derivative of the real code (a diff of a diff), |
444 but also because MQ adds noise to the process by modifying | 444 but also because MQ adds noise to the process by modifying |
445 time stamps and directory names when it updates a | 445 time stamps and directory names when it updates a |
446 patch.</para> | 446 patch.</para> |
447 | 447 |
448 <para>However, you can use the <literal | 448 <para id="x_19b">However, you can use the <literal |
449 role="hg-ext">extdiff</literal> extension, which is bundled | 449 role="hg-ext">extdiff</literal> extension, which is bundled |
450 with Mercurial, to turn a diff of two versions of a patch into | 450 with Mercurial, to turn a diff of two versions of a patch into |
451 something readable. To do this, you will need a third-party | 451 something readable. To do this, you will need a third-party |
452 package called <literal role="package">patchutils</literal> | 452 package called <literal role="package">patchutils</literal> |
453 <citation>web:patchutils</citation>. This provides a command | 453 <citation>web:patchutils</citation>. This provides a command |
454 named <command>interdiff</command>, which shows the | 454 named <command>interdiff</command>, which shows the |
455 differences between two diffs as a diff. Used on two versions | 455 differences between two diffs as a diff. Used on two versions |
456 of the same diff, it generates a diff that represents the diff | 456 of the same diff, it generates a diff that represents the diff |
457 from the first to the second version.</para> | 457 from the first to the second version.</para> |
458 | 458 |
459 <para>You can enable the <literal | 459 <para id="x_19c">You can enable the <literal |
460 role="hg-ext">extdiff</literal> extension in the usual way, | 460 role="hg-ext">extdiff</literal> extension in the usual way, |
461 by adding a line to the <literal | 461 by adding a line to the <literal |
462 role="rc-extensions">extensions</literal> section of your | 462 role="rc-extensions">extensions</literal> section of your |
463 <filename role="special">~/.hgrc</filename>.</para> | 463 <filename role="special">~/.hgrc</filename>.</para> |
464 <programlisting>[extensions] | 464 <programlisting>[extensions] |
465 extdiff =</programlisting> | 465 extdiff =</programlisting> |
466 <para>The <command>interdiff</command> command expects to be | 466 <para id="x_19d">The <command>interdiff</command> command expects to be |
467 passed the names of two files, but the <literal | 467 passed the names of two files, but the <literal |
468 role="hg-ext">extdiff</literal> extension passes the program | 468 role="hg-ext">extdiff</literal> extension passes the program |
469 it runs a pair of directories, each of which can contain an | 469 it runs a pair of directories, each of which can contain an |
470 arbitrary number of files. We thus need a small program that | 470 arbitrary number of files. We thus need a small program that |
471 will run <command>interdiff</command> on each pair of files in | 471 will run <command>interdiff</command> on each pair of files in |
473 role="special">hg-interdiff</filename> in the <filename | 473 role="special">hg-interdiff</filename> in the <filename |
474 class="directory">examples</filename> directory of the | 474 class="directory">examples</filename> directory of the |
475 source code repository that accompanies this book. <!-- | 475 source code repository that accompanies this book. <!-- |
476 &example.hg-interdiff; --></para> | 476 &example.hg-interdiff; --></para> |
477 | 477 |
478 <para>With the <filename role="special">hg-interdiff</filename> | 478 <para id="x_19e">With the <filename role="special">hg-interdiff</filename> |
479 program in your shell's search path, you can run it as | 479 program in your shell's search path, you can run it as |
480 follows, from inside an MQ patch directory:</para> | 480 follows, from inside an MQ patch directory:</para> |
481 <programlisting>hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting> | 481 <programlisting>hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting> |
482 <para>Since you'll probably want to use this long-winded command | 482 <para id="x_19f">Since you'll probably want to use this long-winded command |
483 a lot, you can get <literal role="hg-ext">hgext</literal> to | 483 a lot, you can get <literal role="hg-ext">hgext</literal> to |
484 make it available as a normal Mercurial command, again by | 484 make it available as a normal Mercurial command, again by |
485 editing your <filename | 485 editing your <filename |
486 role="special">~/.hgrc</filename>.</para> | 486 role="special">~/.hgrc</filename>.</para> |
487 <programlisting>[extdiff] | 487 <programlisting>[extdiff] |
488 cmd.interdiff = hg-interdiff</programlisting> | 488 cmd.interdiff = hg-interdiff</programlisting> |
489 <para>This directs <literal role="hg-ext">hgext</literal> to | 489 <para id="x_1a0">This directs <literal role="hg-ext">hgext</literal> to |
490 make an <literal>interdiff</literal> command available, so you | 490 make an <literal>interdiff</literal> command available, so you |
491 can now shorten the previous invocation of <command | 491 can now shorten the previous invocation of <command |
492 role="hg-ext-extdiff">extdiff</command> to something a | 492 role="hg-ext-extdiff">extdiff</command> to something a |
493 little more wieldy.</para> | 493 little more wieldy.</para> |
494 <programlisting>hg interdiff -r A:B my-change.patch</programlisting> | 494 <programlisting>hg interdiff -r A:B my-change.patch</programlisting> |
495 | 495 |
496 <note> | 496 <note> |
497 <para> The <command>interdiff</command> command works well | 497 <para id="x_1a1"> The <command>interdiff</command> command works well |
498 only if the underlying files against which versions of a | 498 only if the underlying files against which versions of a |
499 patch are generated remain the same. If you create a patch, | 499 patch are generated remain the same. If you create a patch, |
500 modify the underlying files, and then regenerate the patch, | 500 modify the underlying files, and then regenerate the patch, |
501 <command>interdiff</command> may not produce useful | 501 <command>interdiff</command> may not produce useful |
502 output.</para> | 502 output.</para> |
503 </note> | 503 </note> |
504 | 504 |
505 <para>The <literal role="hg-ext">extdiff</literal> extension is | 505 <para id="x_1a2">The <literal role="hg-ext">extdiff</literal> extension is |
506 useful for more than merely improving the presentation of MQ | 506 useful for more than merely improving the presentation of MQ |
507 patches. To read more about it, go to section <xref | 507 patches. To read more about it, go to section <xref |
508 linkend="sec:hgext:extdiff"/>.</para> | 508 linkend="sec:hgext:extdiff"/>.</para> |
509 | 509 |
510 </sect2> | 510 </sect2> |