1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/mq.tex	Fri Jun 23 12:15:38 2006 -0700
     1.3 @@ -0,0 +1,136 @@
     1.4 +\chapter{Managing change with Mercurial Queues}
     1.5 +\label{chap:mq}
     1.6 +
     1.7 +\section{The patch management problem}
     1.8 +\label{sec:mq:patch-mgmt}
     1.9 +
    1.10 +Here is a common scenario: you need to install a software package from
    1.11 +source, but you find a bug that you must fix in the source before you
    1.12 +can start using the package.  You make your changes, forget about the
    1.13 +package for a while, and a few months later you need to upgrade to a
    1.14 +newer version of the package.  If the newer version of the package
    1.15 +still has the bug, you must extract your fix from the older source
    1.16 +tree and apply it against the newer version.  This is a tedious task,
    1.17 +and it's easy to make mistakes.
    1.18 +
    1.19 +This is a simple case of the ``patch management'' problem.  You have
    1.20 +an ``upstream'' source tree that you can't change; you need to make
    1.21 +some local changes on top of the upstream tree; and you'd like to be
    1.22 +able to keep those changes separate, so that you can apply them to
    1.23 +newer versions of the upstream source.
    1.24 +
    1.25 +The patch management problem arises in many situations.  Probably the
    1.26 +most visible is that a user of an open source software project will
    1.27 +contribute a bugfix or new feature to the project's maintainers in the
    1.28 +form of a patch.
    1.29 +
    1.30 +Distributors of operating systems that include open source software
    1.31 +often need to make changes to the packages they distribute so that
    1.32 +they will build properly in their environments.
    1.33 +
    1.34 +When you have few changes to maintain, it is easy to manage a single
    1.35 +patch using the standard \texttt{diff} and \texttt{patch} programs.
    1.36 +Once the number of changes grows, it starts to makes sense to maintain
    1.37 +patches as discrete ``chunks of work,'' so that for example a single
    1.38 +patch will contain only one bug fix (the patch might modify several
    1.39 +files, but it's doing ``only one thing''), and you may have a number
    1.40 +of such patches for different bugs you need fixed and local changes
    1.41 +you require.  In this situation, if you submit a bugfix patch to the
    1.42 +upstream maintainers of a package and they include your fix in a
    1.43 +subsequent release, you can simply drop that single patch when you're
    1.44 +updating to the newer release.
    1.45 +
    1.46 +Maintaining a single patch against an upstream tree is a little
    1.47 +tedious and error-prone, but not difficult.  However, the complexity
    1.48 +of the problem grows rapidly as the number of patches you have to
    1.49 +maintain increases.  With more than a tiny number of patches in hand,
    1.50 +understanding which ones you have applied and maintaining them moves
    1.51 +from messy to overwhelming.
    1.52 +
    1.53 +Fortunately, Mercurial includes a powerful extension, Mercurial Queues
    1.54 +(or simply ``MQ''), that massively simplifies the patch management
    1.55 +problem.
    1.56 +
    1.57 +\section{The prehistory of Mercurial Queues}
    1.58 +\label{sec:mq:history}
    1.59 +
    1.60 +During the late 1990s, several Linux kernel developers started to
    1.61 +maintain ``patch series'' that modified the behaviour of the Linux
    1.62 +kernel.  Some of these series were focused on stability, some on
    1.63 +feature coverage, and others were more speculative.
    1.64 +
    1.65 +The sizes of these patch series grew rapidly.  In 2002, Andrew Morton
    1.66 +published some shell scripts he had been using to automate the task of
    1.67 +managing his patch queues.  Andrew was successfully using these
    1.68 +scripts to manage hundreds (sometimes thousands) of patches on top of
    1.69 +the Linux kernel.
    1.70 +
    1.71 +\subsection{A patchwork quilt}
    1.72 +\label{sec:mq:quilt}
    1.73 +
    1.74 +
    1.75 +In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the
    1.76 +approach of Andrew's scripts and published a tool called
    1.77 +\href{http://savannah.nongnu.org/projects/quilt}{``patchwork quilt''},
    1.78 +or simply ``quilt''.  Because quilt substantially automated patch
    1.79 +management, it rapidly gained a large following among open source
    1.80 +software developers.
    1.81 +
    1.82 +Quilt manages a \emph{stack of patches} on top of a directory tree.
    1.83 +To begin, you tell quilt to manage a directory tree; it stores away
    1.84 +the names and contents of all files in the tree.  To fix a bug, you
    1.85 +create a new patch (using a single command), edit the files you need
    1.86 +to fix, then ``refresh'' the patch.  
    1.87 +
    1.88 +The refresh step causes quilt to scan the directory tree; it updates
    1.89 +the patch with all of the changes you have made.  You can create
    1.90 +another patch on top of the first, which will track the changes
    1.91 +required to modify the tree from ``tree with one patch applied'' to
    1.92 +``tree with two patches applied''.
    1.93 +
    1.94 +You can \emph{change} which patches are applied to the tree.  If you
    1.95 +``pop'' a patch, the changes made by that patch will vanish from the
    1.96 +directory tree.  Quilt remembers which patches you have popped,
    1.97 +though, so you can ``push'' a popped patch again, and the directory
    1.98 +tree will be restored to contain the modifications in the patch.  Most
    1.99 +importantly, you can run the ``refresh'' command at any time, and the
   1.100 +topmost applied patch will be updated.  This means that you can, at
   1.101 +any time, change both which patches are applied and what
   1.102 +modifications those patches make.
   1.103 +
   1.104 +Quilt knows nothing about revision control tools, so it works equally
   1.105 +well on top of an unpacked tarball or a Suversion repository.
   1.106 +
   1.107 +\subsection{From patchwork quilt to Mercurial Queues}
   1.108 +\label{sec:mq:quilt-mq}
   1.109 +
   1.110 +In mid-2005, Chris Mason took the features of quilt and wrote an
   1.111 +extension that he called Mercurial Queues, which added quilt-like
   1.112 +behaviour to Mercurial.
   1.113 +
   1.114 +The key difference between quilt and MQ is that quilt knows nothing
   1.115 +about revision control systems, while MQ is \emph{integrated} into
   1.116 +Mercurial.  Each patch that you push is represented as a Mercurial
   1.117 +changeset.  Pop a patch, and the changeset goes away.
   1.118 +
   1.119 +This integration makes understanding patches and debugging their
   1.120 +effects \emph{enormously} easier.  Since every applied patch has an
   1.121 +associated changeset, you can use \hgcmdargs{log}{\emph{filename}} to
   1.122 +see which changesets and patches affected a file.  You can use the
   1.123 +\hgext{bisect} extension to binary-search through all changesets and
   1.124 +applied patches to see where a bug got introduced or fixed.  You can
   1.125 +use the \hgcmd{annotate} command to see which changeset or patch
   1.126 +modified a particular line of a source file.  And so on.
   1.127 +
   1.128 +Because quilt does not care about revision control tools, it is still
   1.129 +a tremendously useful piece of software to know about for situations
   1.130 +where you cannot use Mercurial and MQ.
   1.131 +\section{Section!}
   1.132 +\label{sec:sec}
   1.133 +
   1.134 +Section!
   1.135 +
   1.136 +%%% Local Variables: 
   1.137 +%%% mode: latex
   1.138 +%%% TeX-master: "00book"
   1.139 +%%% End: