1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/ch13-mq-collab.xml	Fri Sep 04 16:33:46 2009 +0200
     1.3 @@ -0,0 +1,499 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<chapter>
     1.7 +<title>Advanced uses of Mercurial Queues</title>
     1.8 +<para>\label{chap:mq-collab}</para>
     1.9 +
    1.10 +<para>While it's easy to pick up straightforward uses of Mercurial Queues,
    1.11 +use of a little discipline and some of MQ's less frequently used
    1.12 +capabilities makes it possible to work in complicated development
    1.13 +environments.</para>
    1.14 +
    1.15 +<para>In this chapter, I will use as an example a technique I have used to
    1.16 +manage the development of an Infiniband device driver for the Linux
    1.17 +kernel.  The driver in question is large (at least as drivers go),
    1.18 +with 25,000 lines of code spread across 35 source files.  It is
    1.19 +maintained by a small team of developers.</para>
    1.20 +
    1.21 +<para>While much of the material in this chapter is specific to Linux, the
    1.22 +same principles apply to any code base for which you're not the
    1.23 +primary owner, and upon which you need to do a lot of development.</para>
    1.24 +
    1.25 +<sect1>
    1.26 +<title>The problem of many targets</title>
    1.27 +
    1.28 +<para>The Linux kernel changes rapidly, and has never been internally
    1.29 +stable; developers frequently make drastic changes between releases.
    1.30 +This means that a version of the driver that works well with a
    1.31 +particular released version of the kernel will not even <emphasis>compile</emphasis>
    1.32 +correctly against, typically, any other version.</para>
    1.33 +
    1.34 +<para>To maintain a driver, we have to keep a number of distinct versions of
    1.35 +Linux in mind.</para>
    1.36 +<itemizedlist>
    1.37 +<listitem><para>One target is the main Linux kernel development tree.
    1.38 +  Maintenance of the code is in this case partly shared by other
    1.39 +  developers in the kernel community, who make <quote>drive-by</quote>
    1.40 +  modifications to the driver as they develop and refine kernel
    1.41 +  subsystems.</para>
    1.42 +</listitem>
    1.43 +<listitem><para>We also maintain a number of <quote>backports</quote> to older versions of
    1.44 +  the Linux kernel, to support the needs of customers who are running
    1.45 +  older Linux distributions that do not incorporate our drivers.  (To
    1.46 +  <emphasis>backport</emphasis> a piece of code is to modify it to work in an older
    1.47 +  version of its target environment than the version it was developed
    1.48 +  for.)</para>
    1.49 +</listitem>
    1.50 +<listitem><para>Finally, we make software releases on a schedule that is
    1.51 +  necessarily not aligned with those used by Linux distributors and
    1.52 +  kernel developers, so that we can deliver new features to customers
    1.53 +  without forcing them to upgrade their entire kernels or
    1.54 +  distributions.
    1.55 +</para>
    1.56 +</listitem></itemizedlist>
    1.57 +
    1.58 +<sect2>
    1.59 +<title>Tempting approaches that don't work well</title>
    1.60 +
    1.61 +<para>There are two <quote>standard</quote> ways to maintain a piece of software that
    1.62 +has to target many different environments.
    1.63 +</para>
    1.64 +
    1.65 +<para>The first is to maintain a number of branches, each intended for a
    1.66 +single target.  The trouble with this approach is that you must
    1.67 +maintain iron discipline in the flow of changes between repositories.
    1.68 +A new feature or bug fix must start life in a <quote>pristine</quote> repository,
    1.69 +then percolate out to every backport repository.  Backport changes are
    1.70 +more limited in the branches they should propagate to; a backport
    1.71 +change that is applied to a branch where it doesn't belong will
    1.72 +probably stop the driver from compiling.
    1.73 +</para>
    1.74 +
    1.75 +<para>The second is to maintain a single source tree filled with conditional
    1.76 +statements that turn chunks of code on or off depending on the
    1.77 +intended target.  Because these <quote>ifdefs</quote> are not allowed in the
    1.78 +Linux kernel tree, a manual or automatic process must be followed to
    1.79 +strip them out and yield a clean tree.  A code base maintained in this
    1.80 +fashion rapidly becomes a rat's nest of conditional blocks that are
    1.81 +difficult to understand and maintain.
    1.82 +</para>
    1.83 +
    1.84 +<para>Neither of these approaches is well suited to a situation where you
    1.85 +don't <quote>own</quote> the canonical copy of a source tree.  In the case of a
    1.86 +Linux driver that is distributed with the standard kernel, Linus's
    1.87 +tree contains the copy of the code that will be treated by the world
    1.88 +as canonical.  The upstream version of <quote>my</quote> driver can be modified
    1.89 +by people I don't know, without me even finding out about it until
    1.90 +after the changes show up in Linus's tree.
    1.91 +</para>
    1.92 +
    1.93 +<para>These approaches have the added weakness of making it difficult to
    1.94 +generate well-formed patches to submit upstream.
    1.95 +</para>
    1.96 +
    1.97 +<para>In principle, Mercurial Queues seems like a good candidate to manage a
    1.98 +development scenario such as the above.  While this is indeed the
    1.99 +case, MQ contains a few added features that make the job more
   1.100 +pleasant.
   1.101 +</para>
   1.102 +
   1.103 +<para>\section{Conditionally applying patches with
   1.104 +  guards}
   1.105 +</para>
   1.106 +
   1.107 +<para>Perhaps the best way to maintain sanity with so many targets is to be
   1.108 +able to choose specific patches to apply for a given situation.  MQ
   1.109 +provides a feature called <quote>guards</quote> (which originates with quilt's
   1.110 +<literal>guards</literal> command) that does just this.  To start off, let's
   1.111 +create a simple repository for experimenting in.
   1.112 +<!-- &interaction.mq.guards.init; -->
   1.113 +This gives us a tiny repository that contains two patches that don't
   1.114 +have any dependencies on each other, because they touch different files.
   1.115 +</para>
   1.116 +
   1.117 +<para>The idea behind conditional application is that you can <quote>tag</quote> a
   1.118 +patch with a <emphasis>guard</emphasis>, which is simply a text string of your
   1.119 +choosing, then tell MQ to select specific guards to use when applying
   1.120 +patches.  MQ will then either apply, or skip over, a guarded patch,
   1.121 +depending on the guards that you have selected.
   1.122 +</para>
   1.123 +
   1.124 +<para>A patch can have an arbitrary number of guards;
   1.125 +each one is <emphasis>positive</emphasis> (<quote>apply this patch if this guard is
   1.126 +selected</quote>) or <emphasis>negative</emphasis> (<quote>skip this patch if this guard is
   1.127 +selected</quote>).  A patch with no guards is always applied.
   1.128 +</para>
   1.129 +
   1.130 +</sect2>
   1.131 +</sect1>
   1.132 +<sect1>
   1.133 +<title>Controlling the guards on a patch</title>
   1.134 +
   1.135 +<para>The <command role="hg-ext-mq">qguard</command> command lets you determine which guards should
   1.136 +apply to a patch, or display the guards that are already in effect.
   1.137 +Without any arguments, it displays the guards on the current topmost
   1.138 +patch.
   1.139 +<!-- &interaction.mq.guards.qguard; -->
   1.140 +To set a positive guard on a patch, prefix the name of the guard with
   1.141 +a <quote><literal>+</literal></quote>.
   1.142 +<!-- &interaction.mq.guards.qguard.pos; -->
   1.143 +To set a negative guard on a patch, prefix the name of the guard with
   1.144 +a <quote><literal>-</literal></quote>.
   1.145 +<!-- &interaction.mq.guards.qguard.neg; -->
   1.146 +</para>
   1.147 +
   1.148 +<note>
   1.149 +<para>  The <command role="hg-ext-mq">qguard</command> command <emphasis>sets</emphasis> the guards on a patch; it
   1.150 +  doesn't <emphasis>modify</emphasis> them.  What this means is that if you run
   1.151 +  <command role="hg-cmd">hg qguard +a +b</command> on a patch, then <command role="hg-cmd">hg qguard +c</command> on
   1.152 +  the same patch, the <emphasis>only</emphasis> guard that will be set on it
   1.153 +  afterwards is <literal>+c</literal>.
   1.154 +</para>
   1.155 +</note>
   1.156 +
   1.157 +<para>Mercurial stores guards in the <filename role="special">series</filename> file; the form in
   1.158 +which they are stored is easy both to understand and to edit by hand.
   1.159 +(In other words, you don't have to use the <command role="hg-ext-mq">qguard</command> command if
   1.160 +you don't want to; it's okay to simply edit the <filename role="special">series</filename>
   1.161 +file.)
   1.162 +<!-- &interaction.mq.guards.series; -->
   1.163 +</para>
   1.164 +
   1.165 +</sect1>
   1.166 +<sect1>
   1.167 +<title>Selecting the guards to use</title>
   1.168 +
   1.169 +<para>The <command role="hg-ext-mq">qselect</command> command determines which guards are active at a
   1.170 +given time.  The effect of this is to determine which patches MQ will
   1.171 +apply the next time you run <command role="hg-ext-mq">qpush</command>.  It has no other effect; in
   1.172 +particular, it doesn't do anything to patches that are already
   1.173 +applied.
   1.174 +</para>
   1.175 +
   1.176 +<para>With no arguments, the <command role="hg-ext-mq">qselect</command> command lists the guards
   1.177 +currently in effect, one per line of output.  Each argument is treated
   1.178 +as the name of a guard to apply.
   1.179 +<!-- &interaction.mq.guards.qselect.foo; -->
   1.180 +In case you're interested, the currently selected guards are stored in
   1.181 +the <filename role="special">guards</filename> file.
   1.182 +<!-- &interaction.mq.guards.qselect.cat; -->
   1.183 +We can see the effect the selected guards have when we run
   1.184 +<command role="hg-ext-mq">qpush</command>.
   1.185 +<!-- &interaction.mq.guards.qselect.qpush; -->
   1.186 +</para>
   1.187 +
   1.188 +<para>A guard cannot start with a <quote><literal>+</literal></quote> or <quote><literal>-</literal></quote>
   1.189 +character.  The name of a guard must not contain white space, but most
   1.190 +other characters are acceptable.  If you try to use a guard with an
   1.191 +invalid name, MQ will complain:
   1.192 +<!-- &interaction.mq.guards.qselect.error; -->
   1.193 +Changing the selected guards changes the patches that are applied.
   1.194 +<!-- &interaction.mq.guards.qselect.quux; -->
   1.195 +You can see in the example below that negative guards take precedence
   1.196 +over positive guards.
   1.197 +<!-- &interaction.mq.guards.qselect.foobar; -->
   1.198 +</para>
   1.199 +
   1.200 +</sect1>
   1.201 +<sect1>
   1.202 +<title>MQ's rules for applying patches</title>
   1.203 +
   1.204 +<para>The rules that MQ uses when deciding whether to apply a patch
   1.205 +are as follows.
   1.206 +</para>
   1.207 +<itemizedlist>
   1.208 +<listitem><para>A patch that has no guards is always applied.
   1.209 +</para>
   1.210 +</listitem>
   1.211 +<listitem><para>If the patch has any negative guard that matches any currently
   1.212 +  selected guard, the patch is skipped.
   1.213 +</para>
   1.214 +</listitem>
   1.215 +<listitem><para>If the patch has any positive guard that matches any currently
   1.216 +  selected guard, the patch is applied.
   1.217 +</para>
   1.218 +</listitem>
   1.219 +<listitem><para>If the patch has positive or negative guards, but none matches
   1.220 +  any currently selected guard, the patch is skipped.
   1.221 +</para>
   1.222 +</listitem></itemizedlist>
   1.223 +
   1.224 +</sect1>
   1.225 +<sect1>
   1.226 +<title>Trimming the work environment</title>
   1.227 +
   1.228 +<para>In working on the device driver I mentioned earlier, I don't apply the
   1.229 +patches to a normal Linux kernel tree.  Instead, I use a repository
   1.230 +that contains only a snapshot of the source files and headers that are
   1.231 +relevant to Infiniband development.  This repository is 1% the size
   1.232 +of a kernel repository, so it's easier to work with.
   1.233 +</para>
   1.234 +
   1.235 +<para>I then choose a <quote>base</quote> version on top of which the patches are
   1.236 +applied.  This is a snapshot of the Linux kernel tree as of a revision
   1.237 +of my choosing.  When I take the snapshot, I record the changeset ID
   1.238 +from the kernel repository in the commit message.  Since the snapshot
   1.239 +preserves the <quote>shape</quote> and content of the relevant parts of the
   1.240 +kernel tree, I can apply my patches on top of either my tiny
   1.241 +repository or a normal kernel tree.
   1.242 +</para>
   1.243 +
   1.244 +<para>Normally, the base tree atop which the patches apply should be a
   1.245 +snapshot of a very recent upstream tree.  This best facilitates the
   1.246 +development of patches that can easily be submitted upstream with few
   1.247 +or no modifications.
   1.248 +</para>
   1.249 +
   1.250 +</sect1>
   1.251 +<sect1>
   1.252 +<title>Dividing up the <filename role="special">series</filename> file</title>
   1.253 +
   1.254 +<para>I categorise the patches in the <filename role="special">series</filename> file into a number
   1.255 +of logical groups.  Each section of like patches begins with a block
   1.256 +of comments that describes the purpose of the patches that follow.
   1.257 +</para>
   1.258 +
   1.259 +<para>The sequence of patch groups that I maintain follows.  The ordering of
   1.260 +these groups is important; I'll describe why after I introduce the
   1.261 +groups.
   1.262 +</para>
   1.263 +<itemizedlist>
   1.264 +<listitem><para>The <quote>accepted</quote> group.  Patches that the development team has
   1.265 +  submitted to the maintainer of the Infiniband subsystem, and which
   1.266 +  he has accepted, but which are not present in the snapshot that the
   1.267 +  tiny repository is based on.  These are <quote>read only</quote> patches,
   1.268 +  present only to transform the tree into a similar state as it is in
   1.269 +  the upstream maintainer's repository.
   1.270 +</para>
   1.271 +</listitem>
   1.272 +<listitem><para>The <quote>rework</quote> group.  Patches that I have submitted, but that
   1.273 +  the upstream maintainer has requested modifications to before he
   1.274 +  will accept them.
   1.275 +</para>
   1.276 +</listitem>
   1.277 +<listitem><para>The <quote>pending</quote> group.  Patches that I have not yet submitted to
   1.278 +  the upstream maintainer, but which we have finished working on.
   1.279 +  These will be <quote>read only</quote> for a while.  If the upstream maintainer
   1.280 +  accepts them upon submission, I'll move them to the end of the
   1.281 +  <quote>accepted</quote> group.  If he requests that I modify any, I'll move
   1.282 +  them to the beginning of the <quote>rework</quote> group.
   1.283 +</para>
   1.284 +</listitem>
   1.285 +<listitem><para>The <quote>in progress</quote> group.  Patches that are actively being
   1.286 +  developed, and should not be submitted anywhere yet.
   1.287 +</para>
   1.288 +</listitem>
   1.289 +<listitem><para>The <quote>backport</quote> group.  Patches that adapt the source tree to
   1.290 +  older versions of the kernel tree.
   1.291 +</para>
   1.292 +</listitem>
   1.293 +<listitem><para>The <quote>do not ship</quote> group.  Patches that for some reason should
   1.294 +  never be submitted upstream.  For example, one such patch might
   1.295 +  change embedded driver identification strings to make it easier to
   1.296 +  distinguish, in the field, between an out-of-tree version of the
   1.297 +  driver and a version shipped by a distribution vendor.
   1.298 +</para>
   1.299 +</listitem></itemizedlist>
   1.300 +
   1.301 +<para>Now to return to the reasons for ordering groups of patches in this
   1.302 +way.  We would like the lowest patches in the stack to be as stable as
   1.303 +possible, so that we will not need to rework higher patches due to
   1.304 +changes in context.  Putting patches that will never be changed first
   1.305 +in the <filename role="special">series</filename> file serves this purpose.
   1.306 +</para>
   1.307 +
   1.308 +<para>We would also like the patches that we know we'll need to modify to be
   1.309 +applied on top of a source tree that resembles the upstream tree as
   1.310 +closely as possible.  This is why we keep accepted patches around for
   1.311 +a while.
   1.312 +</para>
   1.313 +
   1.314 +<para>The <quote>backport</quote> and <quote>do not ship</quote> patches float at the end of the
   1.315 +<filename role="special">series</filename> file.  The backport patches must be applied on top
   1.316 +of all other patches, and the <quote>do not ship</quote> patches might as well
   1.317 +stay out of harm's way.
   1.318 +</para>
   1.319 +
   1.320 +</sect1>
   1.321 +<sect1>
   1.322 +<title>Maintaining the patch series</title>
   1.323 +
   1.324 +<para>In my work, I use a number of guards to control which patches are to
   1.325 +be applied.
   1.326 +</para>
   1.327 +
   1.328 +<itemizedlist>
   1.329 +<listitem><para><quote>Accepted</quote> patches are guarded with <literal>accepted</literal>.  I
   1.330 +  enable this guard most of the time.  When I'm applying the patches
   1.331 +  on top of a tree where the patches are already present, I can turn
   1.332 +  this patch off, and the patches that follow it will apply cleanly.
   1.333 +</para>
   1.334 +</listitem>
   1.335 +<listitem><para>Patches that are <quote>finished</quote>, but not yet submitted, have no
   1.336 +  guards.  If I'm applying the patch stack to a copy of the upstream
   1.337 +  tree, I don't need to enable any guards in order to get a reasonably
   1.338 +  safe source tree.
   1.339 +</para>
   1.340 +</listitem>
   1.341 +<listitem><para>Those patches that need reworking before being resubmitted are
   1.342 +  guarded with <literal>rework</literal>.
   1.343 +</para>
   1.344 +</listitem>
   1.345 +<listitem><para>For those patches that are still under development, I use
   1.346 +  <literal>devel</literal>.
   1.347 +</para>
   1.348 +</listitem>
   1.349 +<listitem><para>A backport patch may have several guards, one for each version
   1.350 +  of the kernel to which it applies.  For example, a patch that
   1.351 +  backports a piece of code to 2.6.9 will have a <literal>2.6.9</literal> guard.
   1.352 +</para>
   1.353 +</listitem></itemizedlist>
   1.354 +<para>This variety of guards gives me considerable flexibility in
   1.355 +determining what kind of source tree I want to end up with.  For most
   1.356 +situations, the selection of appropriate guards is automated during
   1.357 +the build process, but I can manually tune the guards to use for less
   1.358 +common circumstances.
   1.359 +</para>
   1.360 +
   1.361 +<sect2>
   1.362 +<title>The art of writing backport patches</title>
   1.363 +
   1.364 +<para>Using MQ, writing a backport patch is a simple process.  All such a
   1.365 +patch has to do is modify a piece of code that uses a kernel feature
   1.366 +not present in the older version of the kernel, so that the driver
   1.367 +continues to work correctly under that older version.
   1.368 +</para>
   1.369 +
   1.370 +<para>A useful goal when writing a good backport patch is to make your code
   1.371 +look as if it was written for the older version of the kernel you're
   1.372 +targeting.  The less obtrusive the patch, the easier it will be to
   1.373 +understand and maintain.  If you're writing a collection of backport
   1.374 +patches to avoid the <quote>rat's nest</quote> effect of lots of
   1.375 +<literal>#ifdef</literal>s (hunks of source code that are only used
   1.376 +conditionally) in your code, don't introduce version-dependent
   1.377 +<literal>#ifdef</literal>s into the patches.  Instead, write several patches,
   1.378 +each of which makes unconditional changes, and control their
   1.379 +application using guards.
   1.380 +</para>
   1.381 +
   1.382 +<para>There are two reasons to divide backport patches into a distinct
   1.383 +group, away from the <quote>regular</quote> patches whose effects they modify.
   1.384 +The first is that intermingling the two makes it more difficult to use
   1.385 +a tool like the <literal role="hg-ext">patchbomb</literal> extension to automate the process of
   1.386 +submitting the patches to an upstream maintainer.  The second is that
   1.387 +a backport patch could perturb the context in which a subsequent
   1.388 +regular patch is applied, making it impossible to apply the regular
   1.389 +patch cleanly <emphasis>without</emphasis> the earlier backport patch already being
   1.390 +applied.
   1.391 +</para>
   1.392 +
   1.393 +</sect2>
   1.394 +</sect1>
   1.395 +<sect1>
   1.396 +<title>Useful tips for developing with MQ</title>
   1.397 +
   1.398 +<sect2>
   1.399 +<title>Organising patches in directories</title>
   1.400 +
   1.401 +<para>If you're working on a substantial project with MQ, it's not difficult
   1.402 +to accumulate a large number of patches.  For example, I have one
   1.403 +patch repository that contains over 250 patches.
   1.404 +</para>
   1.405 +
   1.406 +<para>If you can group these patches into separate logical categories, you
   1.407 +can if you like store them in different directories; MQ has no
   1.408 +problems with patch names that contain path separators.
   1.409 +</para>
   1.410 +
   1.411 +</sect2>
   1.412 +<sect2>
   1.413 +<title>Viewing the history of a patch</title>
   1.414 +<para>\label{mq-collab:tips:interdiff}
   1.415 +</para>
   1.416 +
   1.417 +<para>If you're developing a set of patches over a long time, it's a good
   1.418 +idea to maintain them in a repository, as discussed in
   1.419 +section <xref linkend="sec:mq:repo"/>.  If you do so, you'll quickly discover that
   1.420 +using the <command role="hg-cmd">hg diff</command> command to look at the history of changes to a
   1.421 +patch is unworkable.  This is in part because you're looking at the
   1.422 +second derivative of the real code (a diff of a diff), but also
   1.423 +because MQ adds noise to the process by modifying time stamps and
   1.424 +directory names when it updates a patch.
   1.425 +</para>
   1.426 +
   1.427 +<para>However, you can use the <literal role="hg-ext">extdiff</literal> extension, which is bundled
   1.428 +with Mercurial, to turn a diff of two versions of a patch into
   1.429 +something readable.  To do this, you will need a third-party package
   1.430 +called <literal role="package">patchutils</literal> <citation>web:patchutils</citation>.  This provides a
   1.431 +command named <command>interdiff</command>, which shows the differences between
   1.432 +two diffs as a diff.  Used on two versions of the same diff, it
   1.433 +generates a diff that represents the diff from the first to the second
   1.434 +version.
   1.435 +</para>
   1.436 +
   1.437 +<para>You can enable the <literal role="hg-ext">extdiff</literal> extension in the usual way, by
   1.438 +adding a line to the <literal role="rc-extensions">extensions</literal> section of your <filename role="special"> /.hgrc</filename>.
   1.439 +</para>
   1.440 +<programlisting>
   1.441 +<para>  [extensions]
   1.442 +  extdiff =
   1.443 +</para>
   1.444 +</programlisting>
   1.445 +<para>The <command>interdiff</command> command expects to be passed the names of two
   1.446 +files, but the <literal role="hg-ext">extdiff</literal> extension passes the program it runs a
   1.447 +pair of directories, each of which can contain an arbitrary number of
   1.448 +files.  We thus need a small program that will run <command>interdiff</command>
   1.449 +on each pair of files in these two directories.  This program is
   1.450 +available as <filename role="special">hg-interdiff</filename> in the <filename class="directory">examples</filename>
   1.451 +directory of the source code repository that accompanies this book.
   1.452 +<!-- &example.hg-interdiff; -->
   1.453 +</para>
   1.454 +
   1.455 +<para>With the <filename role="special">hg-interdiff</filename> program in your shell's search path,
   1.456 +you can run it as follows, from inside an MQ patch directory:
   1.457 +</para>
   1.458 +<programlisting>
   1.459 +<para>  hg extdiff -p hg-interdiff -r A:B my-change.patch
   1.460 +</para>
   1.461 +</programlisting>
   1.462 +<para>Since you'll probably want to use this long-winded command a lot, you
   1.463 +can get <literal role="hg-ext">hgext</literal> to make it available as a normal Mercurial
   1.464 +command, again by editing your <filename role="special"> /.hgrc</filename>.
   1.465 +</para>
   1.466 +<programlisting>
   1.467 +<para>  [extdiff]
   1.468 +  cmd.interdiff = hg-interdiff
   1.469 +</para>
   1.470 +</programlisting>
   1.471 +<para>This directs <literal role="hg-ext">hgext</literal> to make an <literal>interdiff</literal> command
   1.472 +available, so you can now shorten the previous invocation of
   1.473 +<command role="hg-ext-extdiff">extdiff</command> to something a little more wieldy.
   1.474 +</para>
   1.475 +<programlisting>
   1.476 +<para>  hg interdiff -r A:B my-change.patch
   1.477 +</para>
   1.478 +</programlisting>
   1.479 +
   1.480 +<note>
   1.481 +<para>  The <command>interdiff</command> command works well only if the underlying
   1.482 +  files against which versions of a patch are generated remain the
   1.483 +  same.  If you create a patch, modify the underlying files, and then
   1.484 +  regenerate the patch, <command>interdiff</command> may not produce useful
   1.485 +  output.
   1.486 +</para>
   1.487 +</note>
   1.488 +
   1.489 +<para>The <literal role="hg-ext">extdiff</literal> extension is useful for more than merely improving
   1.490 +the presentation of MQ patches.  To read more about it, go to
   1.491 +section <xref linkend="sec:hgext:extdiff"/>.
   1.492 +</para>
   1.493 +
   1.494 +</sect2>
   1.495 +</sect1>
   1.496 +</chapter>
   1.497 +
   1.498 +<!--
   1.499 +local variables: 
   1.500 +sgml-parent-document: ("00book.xml" "book" "chapter")
   1.501 +end:
   1.502 +-->
   1.503 \ No newline at end of file