Mercurial > hgbook
changeset 352:4cbbb68d7840
branch merged
| author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
|---|---|
| date | Tue, 19 Aug 2008 16:06:16 +0900 |
| parents | 32d33b238b7e (current diff) f3fa98815193 (diff) |
| children | 89a903605c74 |
| files | |
| diffstat | 2 files changed, 197 insertions(+), 100 deletions(-) [+] |
line wrap: on
line diff
--- a/ja/mq-collab.tex Tue Aug 19 16:03:33 2008 +0900 +++ b/ja/mq-collab.tex Tue Aug 19 16:06:16 2008 +0900 @@ -1,112 +1,200 @@ -\chapter{Advanced uses of Mercurial Queues} +%\chapter{Advanced uses of Mercurial Queues} +\chapter{Mercurial Queues$B$N9bEY$J;H$$J}(B} \label{chap:mq-collab} -While it's easy to pick up straightforward uses of Mercurial Queues, -use of a little discipline and some of MQ's less frequently used -capabilities makes it possible to work in complicated development -environments. +%While it's easy to pick up straightforward uses of Mercurial Queues, +%use of a little discipline and some of MQ's less frequently used +%capabilities makes it possible to work in complicated development +%environments. + +Mercurial Queues$B$NC1=c$J;H$$J}$r<h$j>e$2$?0lJ}!$>/!9$NE}@)$H(BMQ$B$N$"$^$jMQ(B +$B$$$i$l$J$$5!G=$rMQ$$$k$3$H$GJ#;($J3+H/4D6-$G$N:n6H$,2DG=$H$J$k!%(B + +%In this chapter, I will use as an example a technique I have used to +%manage the development of an Infiniband device driver for the Linux +%kernel. The driver in question is large (at least as drivers go), +%with 25,000 lines of code spread across 35 source files. It is +%maintained by a small team of developers. -In this chapter, I will use as an example a technique I have used to -manage the development of an Infiniband device driver for the Linux -kernel. The driver in question is large (at least as drivers go), -with 25,000 lines of code spread across 35 source files. It is -maintained by a small team of developers. +$B$3$N>O$G$O!$(BLinux$B%+!<%M%kMQ(BInfiniband$B%G%P%$%9%I%i%$%P$N3+H/$r4IM}$9$k$N$K(B +$BMQ$$$?%F%/%K%C%/$rNc$H$7$FMQ$$$k!%$3$N%I%i%$%P$O!J%I%i%$%P$H$7$F$O!KBg5,(B +$BLO$G!$(B35$B$N%=!<%9%U%!%$%k$K$o$?$k(B25000$B9T$+$i$J$k!%$3$N%=!<%9$O>.5,LO$J3+H/(B +$B<T$N%A!<%`$K$h$C$F$$;~4IM}$5$l$F$$$k!%(B + +%While much of the material in this chapter is specific to Linux, the +%same principles apply to any code base for which you're not the +%primary owner, and upon which you need to do a lot of development. -While much of the material in this chapter is specific to Linux, the -same principles apply to any code base for which you're not the -primary owner, and upon which you need to do a lot of development. +$B$3$N>O$G$NAG:`$O(BLinux$B$KFC2=$7$F$$$k$,!$F1$886B'$O$$$+$J$k%3!<%I%Y!<%9$KBP(B +$B$7$F$bE,MQ2DG=$G!$<+J,<+?H$G=jM-$7$F$$$J$$$,!$B?$/$N3+H/$r9T$&I,MW$N$"$k(B +$B%3!<%I$J$I$K$bE,MQ$G$-$k!%(B + -\section{The problem of many targets} +%\section{The problem of many targets} +\section{$B%?!<%2%C%H$,J#?t$"$k$H$$$&LdBj(B} + +%The Linux kernel changes rapidly, and has never been internally +%stable; developers frequently make drastic changes between releases. +%This means that a version of the driver that works well with a +%particular released version of the kernel will not even \emph{compile} +%correctly against, typically, any other version. -The Linux kernel changes rapidly, and has never been internally -stable; developers frequently make drastic changes between releases. -This means that a version of the driver that works well with a -particular released version of the kernel will not even \emph{compile} -correctly against, typically, any other version. +Linux$B%+!<%M%k$O5^B.$KJQ2=$7!$$=$NFbIt$O7h$7$F0lDj$G$O$J$$!%3+H/<T$?$A$OIQ(B +$BHK$K%j%j!<%94V$G7`E*$JJQ99$r9T$&!%$3$N$?$a!$FCDj$N%j%j!<%9%P!<%8%g%s$GNI(B +$B$/F0$$$?%I%i%$%P$,!$Nc$($PJL$N%P!<%8%g%s$G$O@5$7$/%3%s%Q%$%k$9$k$3$H$9$i(B +$B$G$-$J$/$J$k$H$$$&$3$H$r0UL#$9$k!%(B -To maintain a driver, we have to keep a number of distinct versions of -Linux in mind. +%To maintain a driver, we have to keep a number of distinct versions of +%Linux in mind. + +$B%I%i%$%P$r0];}$9$k$?$a$K!$3+H/<T$O$$$/$D$b$NJL$N%P!<%8%g%s$N(BLinux$B$rA[Dj(B +$B$7$J$1$l$P$J$i$J$$!%(B \begin{itemize} -\item One target is the main Linux kernel development tree. - Maintenance of the code is in this case partly shared by other - developers in the kernel community, who make ``drive-by'' - modifications to the driver as they develop and refine kernel - subsystems. -\item We also maintain a number of ``backports'' to older versions of - the Linux kernel, to support the needs of customers who are running - older Linux distributions that do not incorporate our drivers. (To - \emph{backport} a piece of code is to modify it to work in an older - version of its target environment than the version it was developed - for.) -\item Finally, we make software releases on a schedule that is - necessarily not aligned with those used by Linux distributors and - kernel developers, so that we can deliver new features to customers - without forcing them to upgrade their entire kernels or - distributions. +%\item One target is the main Linux kernel development tree. + +% Maintenance of the code is in this case partly shared by other +% developers in the kernel community, who make ``drive-by'' +% modifications to the driver as they develop and refine kernel +% subsystems. +\item $B0l$D$N%?!<%2%C%H$O(BLinux$B%+!<%M%k$N3+H/%D%j!<$G$"$k!%$3$N>l9g!$%3!<%I(B + $B$N0];}4IM}$O%+!<%M%k%3%_%e%K%F%#$NB>$N3+H/<T!J$3$l$O%+!<%M%k$N%5%V(B + $B%7%9%F%`$r2~NI$9$k$?$a$K%I%i%$%P$r(B``$BDI$$N)$F$k(B''$BJQ99$r9T$&3+H/<T$G(B + $B$"$k!K$HItJ,E*$K6&M-$5$l$F$$$k!%(B +%\item We also maintain a number of ``backports'' to older versions of +% the Linux kernel, to support the needs of customers who are running +% older Linux distributions that do not incorporate our drivers. (To +% \emph{backport} a piece of code is to modify it to work in an older +% version of its target environment than the version it was developed +% for.) +\item $B3+H/<T$O2f!9$N%I%i%$%P$,AH$_9~$^$l$F$$$J$$8E$$(BLinux$B%G%#%9%H%j%S%e!<(B + $B%7%g%s$r;H$C$F$$$k8\5R$r%5%]!<%H$9$k$?$a$K!$8E$$%P!<%8%g%s$N(BLinux$B%+!<(B + $B%M%k$X$N(B``$B%P%C%/%]!<%H(B''$B$rJz$($F$$$k!%%3!<%I$N0lIt$r(B\emph{$B%P%C%/%]!<(B + $B%H(B}$B$9$k$3$H$O!$%I%i%$%P$,3+H/$5$l$?%P!<%8%g%s$h$j$b8E$$%P!<%8%g%s(B + $B$N4D6-$GF0$/$h$&$K$9$k$3$H$r0UL#$9$k!%(B +%\item Finally, we make software releases on a schedule that is +% necessarily not aligned with those used by Linux distributors and +% kernel developers, so that we can deliver new features to customers +% without forcing them to upgrade their entire kernels or +% distributions. +\item $B:G=*E*$K(BLinux$B%G%#%9%H%j%S%e!<%?$d%+!<%M%k3+H/<T$rBT$?$;$k$3$H$J$/%9(B +$B%1%8%e!<%kDL$j$K%=%U%H%&%'%"$r%j%j!<%9$9$k$3$H$,I,MW$G$"$j!$$3$l$K$h$C$F(B +$B8\5R$K%+!<%M%k$d%G%#%9%H%j%S%e!<%7%g%sA4BN$r%"%C%W%0%l!<%I$5$;$k$3$H$J$/(B +$B?75!G=$r8\5R$KFO$1$i$l$k!%(B \end{itemize} -\subsection{Tempting approaches that don't work well} +%\subsection{Tempting approaches that don't work well} +\subsection{$B$d$C$F$7$^$$$,$A$J4V0c$C$?J}K!(B} -There are two ``standard'' ways to maintain a piece of software that -has to target many different environments. +%There are two ``standard'' ways to maintain a piece of software that +%has to target many different environments. + +$B$5$^$6$^$J4D6-$r%?!<%2%C%H$K$7$?%=%U%H%&%'%"$r4IM}$9$k(B2$B$D$NI8=`E*$JJ}K!(B +$B$,$"$k!%(B -The first is to maintain a number of branches, each intended for a -single target. The trouble with this approach is that you must -maintain iron discipline in the flow of changes between repositories. -A new feature or bug fix must start life in a ``pristine'' repository, -then percolate out to every backport repository. Backport changes are -more limited in the branches they should propagate to; a backport -change that is applied to a branch where it doesn't belong will -probably stop the driver from compiling. +%The first is to maintain a number of branches, each intended for a +%single target. The trouble with this approach is that you must +%maintain iron discipline in the flow of changes between repositories. +%A new feature or bug fix must start life in a ``pristine'' repository, +%then percolate out to every backport repository. Backport changes are +%more limited in the branches they should propagate to; a backport +%change that is applied to a branch where it doesn't belong will +%probably stop the driver from compiling. + +$BBh(B1$B$NJ}K!$O!$C10l$N%?!<%2%C%H8~$1$NJ#?t$N%V%i%s%A$r0];}$9$k$3$H$G$"$k!%$3(B +$B$NJ}K!$NLdBjE@$O!$%j%]%8%H%j4V$G$NJQ99$NN.$l$K$D$$$F873J$J5,N'$r0];}$7$J(B +$B$1$l$P$J$i$J$$$3$H$G$"$k!%?75!G=$d%P%0=$@5$O!$$-$l$$$J>uBV$N%j%]%8%H%j$G(B +$B3+;O$7!$%P%C%/%]!<%H%j%]%8%H%j$K?;F)$9$kI,MW$,$"$k!%%P%C%/%]!<%HJQ99$OGH(B +$B5Z$9$Y$-%V%i%s%AFb$K8BDj$5$l$F$$$J$1$l$P$J$i$J$$!%I,MW$N$J$$%V%i%s%A$X$N(B +$B%P%C%/%]!<%H$NGH5Z$O$*$=$i$/%I%i%$%P$r%3%s%Q%$%kITG=$K$7$F$7$^$&$@$m$&!%(B -The second is to maintain a single source tree filled with conditional -statements that turn chunks of code on or off depending on the -intended target. Because these ``ifdefs'' are not allowed in the -Linux kernel tree, a manual or automatic process must be followed to -strip them out and yield a clean tree. A code base maintained in this -fashion rapidly becomes a rat's nest of conditional blocks that are -difficult to understand and maintain. +%The second is to maintain a single source tree filled with conditional +%statements that turn chunks of code on or off depending on the +%intended target. Because these ``ifdefs'' are not allowed in the +%Linux kernel tree, a manual or automatic process must be followed to +%strip them out and yield a clean tree. A code base maintained in this +%fashion rapidly becomes a rat's nest of conditional blocks that are +%difficult to understand and maintain. + +$BBh(B2$B$NJ}K!$O!$%A%c%s%/$d%3!<%I$r!$L\E*$H$9$k%?!<%2%C%HKh$K(Bon/off$B$9$k>r7oJ8(B +$B$rDI2C$7$?C10l$N%=!<%9%D%j!<$r0];}$9$kJ}K!$G$"$k!%$3$l$i$N(B``ifdef''$B$O(B +linux$B%+!<%M%k%D%j!<$G$O5v$5$l$F$$$J$$$?$a!$<jF0$^$?$O<+F0$G$3$l$i$N%3!<%I(B +$B$r=|5n$7!$%/%j!<%s$J%D%j!<$r:n$k%W%m%;%9$,I,MW$K$J$k!%$3$N$h$&$J$d$jJ}$G(B +$B4IM}$5$l$?%3!<%I%Y!<%9$O$9$0$K>r7o@a$NAc7"$H2=$7!"M}2r$d4IM}$NK8$2$H$J$k!#(B -Neither of these approaches is well suited to a situation where you -don't ``own'' the canonical copy of a source tree. In the case of a -Linux driver that is distributed with the standard kernel, Linus's -tree contains the copy of the code that will be treated by the world -as canonical. The upstream version of ``my'' driver can be modified -by people I don't know, without me even finding out about it until -after the changes show up in Linus's tree. +%Neither of these approaches is well suited to a situation where you +%don't ``own'' the canonical copy of a source tree. In the case of a + +%Linux driver that is distributed with the standard kernel, Linus's +%tree contains the copy of the code that will be treated by the world +%as canonical. The upstream version of ``my'' driver can be modified +%by people I don't know, without me even finding out about it until +%after the changes show up in Linus's tree. + +$B$"$J$?$,@5<0$J%=!<%9%D%j!<$r=jM-$7$F$$$k$N$G$J$1$l$P!"$3$l$i$N$d$jJ}$N$I(B +$B$A$i$b$=$0$o$J$$$@$m$&!#I8=`$N(Blinux$B%+!<%M%k$KF1:-$5$l$F$$$k%I%i%$%P$N>l(B +$B9g!$(BLinus$B$N%D%j!<$O@$3&Cf$G@5<0$J%3!<%I$H$7$F07$o$l$k%3%T!<$r4^$s$G$$$k!%(B +``$B;d(B''$B$N%I%i%$%P$N>eN.HG$O!$CN$i$J$$?M$K$h$C$FJQ99$5$lF@$k$7!$<+J,$NJQ99(B +$B$,(BLinus$B$N%D%j!<$KF~$C$?$"$H$G$5$($bJQ99$5$lF@$k!%(B + +%These approaches have the added weakness of making it difficult to +%generate well-formed patches to submit upstream. -These approaches have the added weakness of making it difficult to -generate well-formed patches to submit upstream. +$B$3$l$i$N%"%W%m!<%A$O!$$&$^$/=q$+$l$?%Q%C%A$r>eN.$XDs=P$9$k$3$H$r:$Fq$K$7(B +$B$F$7$^$&!%(B + +%In principle, Mercurial Queues seems like a good candidate to manage a +%development scenario such as the above. While this is indeed the +%case, MQ contains a few added features that make the job more +%pleasant. + +Mercurial Queues$B$O>e5-$N$h$&$J3+H/%7%J%j%*$r4IM}$9$k$h$$8uJd$N0l$D$G$"$k(B +$B$H$$$($k!%$3$N$h$&$J>l9g$N$?$a$K(BMQ$B$K$O:n6H$r$h$j2wE,$K$9$k$$$/$D$+$N5!G=(B +$B$,$"$k!%(B -In principle, Mercurial Queues seems like a good candidate to manage a -development scenario such as the above. While this is indeed the -case, MQ contains a few added features that make the job more -pleasant. +%\section{Conditionally applying patches with guards} +\section{$B%,!<%I$r;H$C$?%Q%C%A$N>r7oE*$JE,MQ(B} -\section{Conditionally applying patches with - guards} +%Perhaps the best way to maintain sanity with so many targets is to be +%able to choose specific patches to apply for a given situation. MQ +%provides a feature called ``guards'' (which originates with quilt's +%\texttt{guards} command) that does just this. To start off, let's +%create a simple repository for experimenting in. +%\interaction{mq.guards.init} +%This gives us a tiny repository that contains two patches that don't +%have any dependencies on each other, because they touch different files. -Perhaps the best way to maintain sanity with so many targets is to be -able to choose specific patches to apply for a given situation. MQ -provides a feature called ``guards'' (which originates with quilt's -\texttt{guards} command) that does just this. To start off, let's -create a simple repository for experimenting in. +$BB?$/$N%?!<%2%C%H$rBP>]$H$7$J$,$i@5>o$KJ]$D0lHVNI$$J}J}$O!$>u67$K1~$8$FFC(B +$BDj$N%Q%C%A$rA*$Y$k$h$&$K$9$k$3$H$G$"$k!%(BMQ$B$O$3$NL\E*$N$?$a$K(Bquilt$B$N(B +\texttt{guards}$B%3%^%s%I$KN`;w$7$?(B``guards''$B$H8F$P$l$k5!G=$rDs6!$7$F$$$k!%(B +$B3+;O$KEv$?$C$F!$<B83$N$?$a$KC1=c$J%j%]%8%H%j$r:n@.$9$k!%(B \interaction{mq.guards.init} -This gives us a tiny repository that contains two patches that don't -have any dependencies on each other, because they touch different files. +$B>.$5$J%j%]%8%H%j$r:n$j!$JL!9$N%U%!%$%k$rA`:n$9$k8_$$$K0MB8@-$N$J$$(B2$B$D$N%Q%C(B +$B%A$rCV$/!%(B + +%The idea behind conditional application is that you can ``tag'' a +%patch with a \emph{guard}, which is simply a text string of your +%choosing, then tell MQ to select specific guards to use when applying +%patches. MQ will then either apply, or skip over, a guarded patch, +%depending on the guards that you have selected. -The idea behind conditional application is that you can ``tag'' a -patch with a \emph{guard}, which is simply a text string of your -choosing, then tell MQ to select specific guards to use when applying -patches. MQ will then either apply, or skip over, a guarded patch, -depending on the guards that you have selected. +$B>r7oIU$-$G%Q%C%A%Q%C%A$NE,MQ$r%3%s%H%m!<%k$9$kJ}K!$NGX8e$K$"$k$N(B +$B$O!$(B\emph{guard}$B$K$h$C$F%Q%C%A$KIU$1$i$l$?(B``$B%?%0(B''$B$G$"$k!%%?%0$O<+M3$KA*(B +$B$s$@C1=c$J%F%-%9%H$G!$(BMQ$B$,%Q%C%A$rE,MQ$9$k$H$-$KMQ$$$kFCDj$N%,!<%I$r;XDj(B +$B$9$k!%(BMQ$B$O%,!<%I%Q%C%A$NE,MQ$^$?$O%9%-%C%W$r!$;XDj$5$l$?%,!<%I$K$h$C$F7h(B +$BDj$9$k!%(B -A patch can have an arbitrary number of guards; -each one is \emph{positive} (``apply this patch if this guard is -selected'') or \emph{negative} (``skip this patch if this guard is -selected''). A patch with no guards is always applied. +%A patch can have an arbitrary number of guards; +%each one is \emph{positive} (``apply this patch if this guard is +%selected'') or \emph{negative} (``skip this patch if this guard is +%selected''). A patch with no guards is always applied. -\section{Controlling the guards on a patch} +$B%Q%C%A$OG$0U$N?t$N%,!<%I$r;}$D$3$H$,$G$-$k!%3F!9$N%,!<%I(B +$B$O!$(B\emph{positive}$B!J$3$N%,!<%I$,A*Br$5$l$F$$$k$H$-$K$3$N%Q%C%A$rE,MQ!K$^(B +$B$?$O(B\emph{negative}$B!J$3$N%,!<%I$,A*Br$5$l$F$$$k$H$-$K$3$N%Q%C%A$r%9%-%C(B +$B%W!K$G$"$k!%%,!<%I$r;}$?$J$$%Q%C%A$O>o$KE,MQ$5$l$k!%(B + +%\section{Controlling the guards on a patch} +\section{$B%Q%C%AFb$N%,!<%I$rA`:n$9$k(B} The \hgxcmd{mq}{qguard} command lets you determine which guards should apply to a patch, or display the guards that are already in effect. @@ -135,7 +223,8 @@ file.) \interaction{mq.guards.series} -\section{Selecting the guards to use} +%\section{Selecting the guards to use} +\section{$B;HMQ$9$k%,!<%I$rA*$V(B} The \hgxcmd{mq}{qselect} command determines which guards are active at a given time. The effect of this is to determine which patches MQ will @@ -165,7 +254,8 @@ over positive guards. \interaction{mq.guards.qselect.foobar} -\section{MQ's rules for applying patches} +%\section{MQ's rules for applying patches} +\section{MQ$B$N%Q%C%AE,MQ%k!<%k(B} The rules that MQ uses when deciding whether to apply a patch are as follows. @@ -179,7 +269,8 @@ any currently selected guard, the patch is skipped. \end{itemize} -\section{Trimming the work environment} +%\section{Trimming the work environment} +\section{$B:n6H4D6-$r=L>.$9$k(B} In working on the device driver I mentioned earlier, I don't apply the patches to a normal Linux kernel tree. Instead, I use a repository @@ -200,7 +291,8 @@ development of patches that can easily be submitted upstream with few or no modifications. -\section{Dividing up the \sfilename{series} file} +%\section{Dividing up the \sfilename{series} file} +\section{\sfilename{series}$B%U%!%$%k$X%@%$%V$9$k(B} I categorise the patches in the \sfilename{series} file into a number of logical groups. Each section of like patches begins with a block @@ -252,7 +344,8 @@ of all other patches, and the ``do not ship'' patches might as well stay out of harm's way. -\section{Maintaining the patch series} +%\section{Maintaining the patch series} +\section{$B%Q%C%A%7%j!<%:$r4IM}$9$k(B} In my work, I use a number of guards to control which patches are to be applied. @@ -280,7 +373,8 @@ the build process, but I can manually tune the guards to use for less common circumstances. -\subsection{The art of writing backport patches} +%\subsection{The art of writing backport patches} +\subsection{$B%P%C%/%]!<%H%Q%C%A$r=q$/5;=Q(B} Using MQ, writing a backport patch is a simple process. All such a patch has to do is modify a piece of code that uses a kernel feature @@ -308,9 +402,11 @@ patch cleanly \emph{without} the earlier backport patch already being applied. -\section{Useful tips for developing with MQ} +%\section{Useful tips for developing with MQ} +\section{MQ$B$K$h$k3+H/$N(Btips} -\subsection{Organising patches in directories} +%\subsection{Organising patches in directories} +\subsection{$B%G%#%l%/%H%jFb$G%Q%C%A$r4IM}$9$k(B} If you're working on a substantial project with MQ, it's not difficult to accumulate a large number of patches. For example, I have one @@ -320,7 +416,8 @@ can if you like store them in different directories; MQ has no problems with patch names that contain path separators. -\subsection{Viewing the history of a patch} +%\subsection{Viewing the history of a patch} +\subsection{$B%Q%C%A$N%R%9%H%j$r8+$k(B} \label{mq-collab:tips:interdiff} If you're developing a set of patches over a long time, it's a good @@ -387,7 +484,7 @@ the presentation of MQ~patches. To read more about it, go to section~\ref{sec:hgext:extdiff}. -%%% Local Variables: +%%% Local Variables: %%% mode: yatex %%% TeX-master: "00book" -%%% End: +%%% End: