Mercurial > hgbook
changeset 349:84ae26ab0ac3
started mq-collab.tex
| author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
|---|---|
| date | Sat, 16 Aug 2008 12:45:25 +0900 |
| parents | b3e736000aef |
| children | 5a5419eeab70 |
| files | ja/mq-collab.tex ja/todo.txt |
| diffstat | 2 files changed, 103 insertions(+), 55 deletions(-) [+] |
line wrap: on
line diff
--- a/ja/mq-collab.tex Fri Aug 01 16:09:39 2008 +0900 +++ b/ja/mq-collab.tex Sat Aug 16 12:45:25 2008 +0900 @@ -1,51 +1,89 @@ -\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. @@ -73,7 +111,7 @@ 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. +after the changes show up in Linus's tree. These approaches have the added weakness of making it difficult to generate well-formed patches to submit upstream. @@ -83,8 +121,8 @@ case, MQ contains a few added features that make the job more pleasant. -\section{Conditionally applying patches with - guards} +%\section{Conditionally applying patches with guards} +\section{$B%,!<%I$r;H$C$?%Q%C%A$N>r7oE*$JE,MQ(B} 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 @@ -106,7 +144,8 @@ 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} +%\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 +174,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 +205,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 +220,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 +242,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 +295,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 +324,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 +353,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 +367,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 +435,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: