1.1 --- a/en/mq-collab.tex	Fri Oct 20 16:56:20 2006 -0700
     1.2 +++ b/en/mq-collab.tex	Sat Oct 21 11:05:51 2006 -0700
     1.3 @@ -5,11 +5,11 @@
     1.4  capabilities makes it possible to work in complicated development
     1.5  environments.
     1.6  
     1.7 -In this chapter, I will discuss a technique I have developed to manage
     1.8 -the development of an Infiniband device driver for the Linux kernel.
     1.9 -The driver in question is large (at least as drivers go), with 25,000
    1.10 -lines of code spread across 35 source files.  It is maintained by a
    1.11 -small team of developers.
    1.12 +In this chapter, I will use as an example a technique I have used to
    1.13 +manage the development of an Infiniband device driver for the Linux
    1.14 +kernel.  The driver in question is large (at least as drivers go),
    1.15 +with 25,000 lines of code spread across 35 source files.  It is
    1.16 +maintained by a small team of developers.
    1.17  
    1.18  While much of the material in this chapter is specific to Linux, the
    1.19  same principles apply to any code base for which you're not the
    1.20 @@ -33,7 +33,10 @@
    1.21    subsystems.
    1.22  \item We also maintain a number of ``backports'' to older versions of
    1.23    the Linux kernel, to support the needs of customers who are running
    1.24 -  older Linux distributions that do not incorporate our drivers.
    1.25 +  older Linux distributions that do not incorporate our drivers.  (To
    1.26 +  \emph{backport} a piece of code is to modify it to work in an older
    1.27 +  version of its target environment than the version it was developed
    1.28 +  for.)
    1.29  \item Finally, we make software releases on a schedule that is
    1.30    necessarily not aligned with those used by Linux distributors and
    1.31    kernel developers, so that we can deliver new features to customers
    1.32 @@ -79,7 +82,8 @@
    1.33  case, MQ contains a few added features that make the job more
    1.34  pleasant.
    1.35  
    1.36 -\section{Conditionally applying patches with guards}
    1.37 +\section{Conditionally applying patches with 
    1.38 +  guards}
    1.39  
    1.40  Perhaps the best way to maintain sanity with so many targets is to be
    1.41  able to choose specific patches to apply for a given situation.  MQ
    1.42 @@ -150,14 +154,106 @@
    1.43  \interaction{mq.guards.qselect.qpush}
    1.44  
    1.45  A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}''
    1.46 -character.
    1.47 +character.  The name of a guard must start with an alphabetic
    1.48 +character (upper or lower case) or an underscore.  The rest of the
    1.49 +guard's name can contain any of these characters, or a digit.  These
    1.50 +rules are similar to those used for variable naming in most popular
    1.51 +programming languages.  If you try to use a guard with an invalid
    1.52 +name, MQ will complain:
    1.53  \interaction{mq.guards.qselect.error}
    1.54  Changing the selected guards changes the patches that are applied.
    1.55  \interaction{mq.guards.qselect.quux}
    1.56 -You can see here that negative guards take precedence over positive
    1.57 -guards.
    1.58 +You can see in the example below that negative guards take precedence
    1.59 +over positive guards.
    1.60  \interaction{mq.guards.qselect.foobar}
    1.61  
    1.62 +\section{MQ's rules for applying patches}
    1.63 +
    1.64 +The rules that MQ uses when deciding whether to apply a patch
    1.65 +are as follows.
    1.66 +\begin{itemize}
    1.67 +\item A patch that has no guards is always applied.
    1.68 +\item If the patch has any negative guard that matches any currently
    1.69 +  selected guard, the patch is skipped.
    1.70 +\item If the patch has any positive guard that matches any currently
    1.71 +  selected guard, the patch is applied.
    1.72 +\item If the patch has positive or negative guards, but none matches
    1.73 +  any currently selected guard, the patch is skipped.
    1.74 +\end{itemize}
    1.75 +
    1.76 +\section{Trimming the work environment}
    1.77 +
    1.78 +In working on the device driver I mentioned earlier, I don't apply the
    1.79 +patches to a normal Linux kernel tree.  Instead, I use a repository
    1.80 +that contains only a snapshot of the source files and headers that are
    1.81 +relevant to Infiniband development.  This repository is~1\% the size
    1.82 +of a kernel repository, so it's easier to work with.
    1.83 +
    1.84 +I then choose a ``base'' version on top of which the patches are
    1.85 +applied.  This is a snapshot of the Linux kernel tree as of a revision
    1.86 +of my choosing.  When I take the snapshot, I record the changeset ID
    1.87 +from the kernel repository in the commit message.  Since the snapshot
    1.88 +preserves the ``shape'' and content of the relevant parts of the
    1.89 +kernel tree, I can apply my patches on top of either my tiny
    1.90 +repository or a normal kernel tree.
    1.91 +
    1.92 +Normally, the base tree atop which the patches apply should be a
    1.93 +snapshot of a very recent upstream tree.  This best facilitates the
    1.94 +development of patches that can easily be submitted upstream with few
    1.95 +or no modifications.
    1.96 +
    1.97 +\section{Dividing up the \sfilename{series} file}
    1.98 +
    1.99 +I categorise the patches in the \sfilename{series} file into a number
   1.100 +of logical groups.  Each section of like patches begins with a block
   1.101 +of comments that describes the purpose of the patches that follow.
   1.102 +
   1.103 +The sequence of patch groups that I maintain follows.  The ordering of
   1.104 +these groups is important; I'll describe why after I introduce the
   1.105 +groups.
   1.106 +\begin{itemize}
   1.107 +\item The ``accepted'' group.  Patches that the development team has
   1.108 +  submitted to the maintainer of the Infiniband subsystem, and which
   1.109 +  he has accepted, but which are not present in the snapshot that the
   1.110 +  tiny repository is based on.  These are ``read only'' patches,
   1.111 +  present only to transform the tree into a similar state as it is in
   1.112 +  the upstream maintainer's repository.
   1.113 +\item The ``rework'' group.  Patches that I have submitted, but that
   1.114 +  the upstream maintainer has requested modifications to before he
   1.115 +  will accept them.
   1.116 +\item The ``pending'' group.  Patches that I have not yet submitted to
   1.117 +  the upstream maintainer, but which we have finished working on.
   1.118 +  These will be ``read only'' for a while.  If the upstream maintainer
   1.119 +  accepts them upon submission, I'll move them to the end of the
   1.120 +  ``accepted'' group.  If he requests that I modify any, I'll move
   1.121 +  them to the beginning of the ``rework'' group.
   1.122 +\item The ``in progress'' group.  Patches that are actively being
   1.123 +  developed, and should not be submitted anywhere yet.
   1.124 +\item The ``backport'' group.  Patches that adapt the source tree to
   1.125 +  older versions of the kernel tree.
   1.126 +\item The ``do not ship'' group.  Patches that for some reason should
   1.127 +  never be submitted upstream.  For example, one such patch might
   1.128 +  change embedded driver identification strings to make it easier to
   1.129 +  distinguish, in the field, between an out-of-tree version of the
   1.130 +  driver and a version shipped by a distribution vendor.
   1.131 +\end{itemize}
   1.132 +
   1.133 +Now to return to the reasons for ordering groups of patches in this
   1.134 +way.  We would like the lowest patches in the stack to be as stable as
   1.135 +possible, so that we will not need to rework higher patches due to
   1.136 +changes in context.  Putting patches that will never be changed first
   1.137 +in the \sfilename{series} file serves this purpose.
   1.138 +
   1.139 +We would also like the patches that we know we'll need to modify to be
   1.140 +applied on top of a source tree that resembles the upstream tree as
   1.141 +closely as possible.  This is why we keep accepted patches around for
   1.142 +a while.
   1.143 +
   1.144 +The ``backport'' and ``do not ship'' patches float at the end of the
   1.145 +\sfilename{series} file in part because they'll never be shipped
   1.146 +upstream.  Additionally, the backport patches must be applied on top
   1.147 +of all other patches.
   1.148 +
   1.149  %%% Local Variables: 
   1.150  %%% mode: latex
   1.151  %%% TeX-master: "00book"