hgbook
changeset 1:04e469de601e
Early content for chapter on MQ.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Fri Jun 23 12:15:38 2006 -0700 (2006-06-23) |
parents | 76fba5835a1b |
children | 379a802c0210 |
files | en/mq.tex |
line diff
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: