comparison es/mq-collab.tex @ 593:f89480678965

translated section 13.7

591:b7b6a085056e

\interaction{mq.guards.qselect.quux} 
Usted puede ver en el ejemplo de abajo que los guardias negativos
tienen precedencia sobre los guardias positivos.
\interaction{mq.guards.qselect.foobar}

\section{MQ's rules for applying patches}

The rules that MQ uses when deciding whether to apply a patch
are as follows.
\begin{itemize}
\item A patch that has no guards is always applied.
\item If the patch has any negative guard that matches any currently
  selected guard, the patch is skipped.
\item If the patch has any positive guard that matches any currently
  selected guard, the patch is applied.
\item If the patch has positive or negative guards, but none matches
  any currently selected guard, the patch is skipped.
\end{itemize}

\section{Trimming the work environment}

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
that contains only a snapshot of the source files and headers that are
relevant to Infiniband development.  This repository is~1\% the size
of a kernel repository, so it's easier to work with.

I then choose a ``base'' version on top of which the patches are
applied.  This is a snapshot of the Linux kernel tree as of a revision
of my choosing.  When I take the snapshot, I record the changeset ID
from the kernel repository in the commit message.  Since the snapshot
preserves the ``shape'' and content of the relevant parts of the
kernel tree, I can apply my patches on top of either my tiny
repository or a normal kernel tree.

Normally, the base tree atop which the patches apply should be a
snapshot of a very recent upstream tree.  This best facilitates the
development of patches that can easily be submitted upstream with few
or no modifications.

\section{Dividing up the \sfilename{series} file}

I categorise the patches in the \sfilename{series} file into a number
of logical groups.  Each section of like patches begins with a block
of comments that describes the purpose of the patches that follow.

The sequence of patch groups that I maintain follows.  The ordering of
these groups is important; I'll describe why after I introduce the
groups.
\begin{itemize}
\item The ``accepted'' group.  Patches that the development team has
  submitted to the maintainer of the Infiniband subsystem, and which
  he has accepted, but which are not present in the snapshot that the
  tiny repository is based on.  These are ``read only'' patches,
  present only to transform the tree into a similar state as it is in
  the upstream maintainer's repository.
\item The ``rework'' group.  Patches that I have submitted, but that
  the upstream maintainer has requested modifications to before he
  will accept them.
\item The ``pending'' group.  Patches that I have not yet submitted to
  the upstream maintainer, but which we have finished working on.
  These will be ``read only'' for a while.  If the upstream maintainer
  accepts them upon submission, I'll move them to the end of the
  ``accepted'' group.  If he requests that I modify any, I'll move
  them to the beginning of the ``rework'' group.
\item The ``in progress'' group.  Patches that are actively being
  developed, and should not be submitted anywhere yet.
\item The ``backport'' group.  Patches that adapt the source tree to
  older versions of the kernel tree.
\item The ``do not ship'' group.  Patches that for some reason should
  never be submitted upstream.  For example, one such patch might
  change embedded driver identification strings to make it easier to
  distinguish, in the field, between an out-of-tree version of the
  driver and a version shipped by a distribution vendor.
\end{itemize}

Now to return to the reasons for ordering groups of patches in this
way.  We would like the lowest patches in the stack to be as stable as
possible, so that we will not need to rework higher patches due to
changes in context.  Putting patches that will never be changed first
in the \sfilename{series} file serves this purpose.

We would also like the patches that we know we'll need to modify to be
applied on top of a source tree that resembles the upstream tree as
closely as possible.  This is why we keep accepted patches around for
a while.

The ``backport'' and ``do not ship'' patches float at the end of the
\sfilename{series} file.  The backport patches must be applied on top
of all other patches, and the ``do not ship'' patches might as well
stay out of harm's way.

\section{Maintaining the patch series}

In my work, I use a number of guards to control which patches are to
be applied.

\item A backport patch may have several guards, one for each version
  of the kernel to which it applies.  For example, a patch that
  backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard.
\end{itemize}
This variety of guards gives me considerable flexibility in
qdetermining what kind of source tree I want to end up with.  For most
situations, the selection of appropriate guards is automated during
the build process, but I can manually tune the guards to use for less
common circumstances.

\subsection{The art of writing backport patches}

593:f89480678965

\interaction{mq.guards.qselect.quux} 
Usted puede ver en el ejemplo de abajo que los guardias negativos
tienen precedencia sobre los guardias positivos.
\interaction{mq.guards.qselect.foobar}

\section{Reglas de MQ para aplicar parches}

Las reglas que MQ usa para decidir si debe aplicar un parche son las
siguientes.
\begin{itemize}
\item Un parche sin guardias es aplicado siempre.
\item Si el parche tiene algún guardia negativo que corresponda con
  cualquiera de los guardias seleccionados, se salta el parche.
\item Si el parche tiene algún guardia positivo que corresponda con
  cualquiera de los guardias seleccionados, se aplica el parche.
\item Si el parche tiene guardias positivos o negativos, pero ninguno
  corresponde con cualquiera de los guardias seleccionados, se salta
  el parche.
\end{itemize}

\section{Podar el entorno de trabajo}

En el trabajo del controlador de dispositivo que mencioné
anteriormente, yo no aplico los parches a un árbol normal del kernel
de Linux. En cambio, uso un repositorio que sólo contiene una
instantánea de los ficheros fuente y de cabecera que son relevantes
para el desarrollo de Infiniband. Este repositorio tiene un~1\% del
tamaño del repositorio del kernel, por lo que es más fácil trabajar
con él.

Luego escojo una versión ``base'' sobre la cual son aplicados los
parches. Es una instantánea del árbol del kernel de Linux en una
revisión de mi elección. Cuando tomo la instantánea, almaceno el ID de
conjunto de cambios en el mensaje de consignación. Ya que la
instantánea preserva la ``forma'' y el contenido de las partes
relevantes del árbol del kernel, puedo aplicar mis parches sobre mi
pequeño repositorio o sobre un árbol normal del kernel.

Normalmente, el árbol base sobre el que se aplican los parches debería
ser una instantánea de un árbol de desarrollo muy reciente. Esto
facilita mucho el desarrollo de parches que puedan ser enviados al
árbol oficial con pocas o ninguna modificación.

\section{Dividir el fichero \sfilename{series}}

Yo categorizo los parches en el fichero \sfilename{series} en una
serie de grupos lógicos. Cada sección de parches similares empieza con
un bloque de comentarios que describen el propósito de los parches que
le siguen.

La secuencia de grupos de parches que mantengo se muestra a
continuación. El orden de los grupos es importante; explicaré porqué
luego de que presente los grupos.
\begin{itemize}
\item El grupo ``aceptado''. Son parches que el equipo de desarrollo
  ha enviado al mantenedor del subsistema Infiniband, y que él ha
  aceptado, pero que no están presentes en la instantánea en la cual
  está basada el repositorio pequeño. Estos son parches de
  ``sólo lectura'', presentes únicamente para transformar el árbol en
  un estado similar al del repositorio del mantenedor oficial.
\item El grupo ``revisar''. Parches que yo he enviado, pero sobre los
  que que el mantenedor oficial ha solicitado modificaciones antes de
  aceptarlos.
\item El grupo ``pendiente''. Parches que no he enviado al mantenedor
  oficial, pero que ya están terminados. Estos parches serán de
  ``sólo lectura'' por un buen tiempo. Si el mantenedor oficial los
  acepta cuando los envíe, los moveré al final del grupo ``aceptado''.
  Si él solicita que modificaciones en alguno de ellos, los moveré al
  principio del grupo ``revisar''.
\item El grupo ``en proceso''. Parches que están siendo activamente
  desarrollados, y no deberían ser enviados a ninguna parte aún.
\item El grupo ``backport''. Parches que adaptan el árbol de fuentes a
    versiones antiguas del árbol del kernel.
\item El grupo ``no enviar''. Parches que por alguna razón nunca deben
  ser enviados al mantenedor oficial del kernel. Por ejemplo, alguno
  de esos parches podría cambiar las cadenas de identificación
  embebidas del controlador para hacer más fácil la distinción, en
  pruebas de campo, entre una versión del controlador de
  salida-del-árbol  y una versión entregada por un vendedor de alguna
  distribución.
\end{itemize}

Ahora volvemos a las razones para ordenar los grupos de parches en
esta manera. Quisiéramos que los parches del fondo de la pila sean tan
estables como sea posible, para no tener que revisar parches más
arriba debido a cambios de contexto. Poner los parches que nunca
cambiarán en el primer lugar del fichero \sfilename{series} sirve a
este propósito.

También desearíamos que los parches que sabemos que debemos modificar
sean aplicados sobre un árbol de fuentes que se parezca al oficial
tanto como sea posible. Es por esto que mantenemos los parches
aceptados disponibles por una buena cantidad de tiempo.

Los parches ``backport'' y ``no enviar'' flotan al final del fichero
\sfilename{series}. Los parches de backport deben ser aplicados encima
de todos los otros parches, y los parches ``no enviar'' pueden
perfectamente quedarse fuera del camino.

\section{Maintaining the patch series}

In my work, I use a number of guards to control which patches are to
be applied.

\item A backport patch may have several guards, one for each version
  of the kernel to which it applies.  For example, a patch that
  backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard.
\end{itemize}
This variety of guards gives me considerable flexibility in
determining what kind of source tree I want to end up with.  For most
situations, the selection of appropriate guards is automated during
the build process, but I can manually tune the guards to use for less
common circumstances.

\subsection{The art of writing backport patches}