comparison ja/mq-collab.tex @ 350:5a5419eeab70

more mq-collab.tex

349:84ae26ab0ac3

\end{itemize}

%\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.

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 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.

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.

These approaches have the added weakness of making it difficult to
generate well-formed patches to submit upstream.

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}

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.

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,

350:5a5419eeab70

\end{itemize}

%\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.

$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.

$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.

$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.

$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.

$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

%\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
%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.




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,