Mercurial > hgbook
annotate es/mq-collab.tex @ 590:795f2964e104
translated section 13.4
author | Javier Rojas <jerojasro@devnull.li> |
---|---|
date | Wed, 07 Jan 2009 22:26:07 -0500 |
parents | 254888ffaf0a |
children | f89480678965 |
rev | line source |
---|---|
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
1 \chapter{Usos avanzados de las Colas de Mercurial} |
435 | 2 \label{chap:mq-collab} |
3 | |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
4 Auunque es fácil aprender los usos más directos de las Colas de |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
5 Mercurial, tener algo de disciplina junto con algunas de las |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
6 capacidadees menos usadas de MQ hace posible trabajar en entornos de |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
7 desarrollo complejos. |
435 | 8 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
9 En este capítulo, usaré como ejemplo una técnica que he usado para |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
10 administrar el desarrollo de un controlador de dispositivo Infiniband |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
11 para el kernel de Linux. El controlador en cuestión es grande |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
12 (al menos en lo que se refiere a controladores), con 25,000 líneas de |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
13 código esparcidas en 35 ficheros fuente. Es mantenido por un equipo |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
14 pequeño de desarrolladores. |
435 | 15 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
16 Aunque mucho del material en este capítulo es específico de Linux, los |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
17 mismos principios aplican a cualquier base de código de la que usted |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
18 no sea el propietario principal, y sobre la que usted necesita hacer |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
19 un montón de desarrollo. |
435 | 20 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
21 \section{El problema de múltiples objetivos} |
435 | 22 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
23 El kernel de Linux cambia con rapidez, y nunca ha sido estable |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
24 internamente; los desarrolladores hacen cambios drásticos entre |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
25 %TODO no encontré una traducción adecuada para "release". Por eso el |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
26 %cambio |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
27 versiones frecuentemente. Esto significa que una versión del |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
28 controlador que funciona bien con una versión particular del kernel ni |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
29 siquiera \emph{compilará} correctamente contra, típicamente, cualquier |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
30 otra versión. |
435 | 31 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
32 Para mantener un controlador, debemos tener en cuenta una buena |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
33 cantidad de versiones de Linux en mente. |
435 | 34 \begin{itemize} |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
35 \item Un objetivo es el árbol de desarrollo principal del kernel de |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
36 Linux. En este caso el mantenimiento del código es compartido |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
37 parcialmente por otros desarrolladores en la comunidad del kernel, |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
38 %TODO drive-by. |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
39 quienes hacen modificaciones ``de-afán'' al controlador a medida que |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
40 desarrollan y refinan subsistemas en el kernel. |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
41 %TODO backport |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
42 \item También mantenemos algunos ``backports'' para versiones antiguas |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
43 del kernel de Linux, para dar soporte a las necesidades de los |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
44 clientes que están corriendo versiones antiguas de Linux que no |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
45 incorporan nuestros controladores. (Hacer el \emph{backport} de un |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
46 pedazo de código es modificarlo para que trabaje en una versión |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
47 de su entorno objetivo anterior a aquella para la cual fue escrito.) |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
48 \item Finalmente, nosotros liberamos nuestro software de acuerdo a un |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
49 cronograma que no necesariamente está alineado con el que usan los |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
50 distribuidores de Linux y los desarrolladores del kernel, así que |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
51 podemos entregar nuevas características a los clientes sin forzarlos |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
52 a actualizar kernels completos o distribuciones. |
435 | 53 \end{itemize} |
54 | |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
55 \subsection{Aproximaciones tentadoras que no funcionan adecuadamente} |
435 | 56 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
57 Hay dos maneras estándar de mantener una porción de software que debe |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
58 funcionar en muchos entornos diferentes. |
435 | 59 |
584 | 60 La primera es mantener varias ramas, cada una pensada para un único |
61 entorno. El problema de esta aproximación es que usted debe tener una | |
62 disciplina férrea con el flujo de cambios entre repositorios. Una | |
63 nueva característica o un arreglo de fallo deben empezar su vida en un | |
64 repositorio ``prístino'', y luego propagarse a cada repositorio de | |
65 backport. Los cambios para backports están más limitados respecto a | |
66 las ramas a las que deberían propagarse; un cambio para backport que | |
67 es aplicado a una rama en la que no corresponde probablemente hará que | |
68 el controlador no compile. | |
69 | |
70 La segunda es mantener un único árbol de código fuente lleno de | |
71 declaraciones que activen o desactiven secciones de código dependiendo | |
72 del entorno objetivo. Ya que estos ``ifdefs'' no están permitidos en | |
73 el árbol del kernel de Linux, debe seguirse algún proceso manual o | |
74 automático para eliminarlos y producir un árbol limpio. Una base de | |
75 código mantenida de esta manera se convierte rápidamente en un nido de | |
76 ratas de bloques condicionales que son difíciles de entender y | |
77 mantener. | |
435 | 78 |
584 | 79 %TODO canónica? |
80 Ninguno de estos enfoques es adecuado para situaciones en las que | |
81 usted no es ``dueño'' de la copia canónica de un árbol de fuentes. En | |
82 el caso de un controlador de Linux que es distribuido con el kernel | |
83 estándar, el árbol de Linux contiene la copia del código que será | |
84 considerada por el mundo como la canónica. La versión oficial de | |
85 ``mi'' controlador puede ser modificada por gente que no conozco, sin | |
86 que yo siquiera me entere de ello hasta después de que los cambios | |
87 aparecen en el árbol de Linus. | |
435 | 88 |
584 | 89 Estos enfoques tienen la debilidad adicional de dificultar la |
90 %TODO upstream. no no es río arriba | |
91 generación de parches bien formados para enviarlos a la versión | |
92 oficial. | |
435 | 93 |
584 | 94 En principio, las Colas de Mercurial parecen ser un buen candidato |
95 para administrar un escenario de desarrollo como el de arriba. Aunque | |
96 este es de hecho el caso, MQ tiene unas cuantas características | |
97 adicionales que hacen el trabajo más agradable. | |
435 | 98 |
588 | 99 \section{Aplicar parches condicionalmente mediante guardias} |
435 | 100 |
588 | 101 Tal vez la mejor manera de conservar la cordura con tantos entornos |
102 objetivo es poder escoger parches específicos para aplicar para cada | |
103 situación. MQ provee una característica llamada ``guardias'' | |
104 (que se origina del comando \texttt{guards} de Quilt) que hace | |
105 precisamente ésto. Para empezar, creemos un repositorio sencillo para | |
106 experimentar. | |
435 | 107 \interaction{mq.guards.init} |
588 | 108 Esto nos brinda un pequeño repositorio que contiene dos parches que no |
109 tienen ninguna dependencia respecto al otro, porque tocan ficheros | |
110 diferentes. | |
435 | 111 |
588 | 112 La idea detrás de la aplicación condicional es que usted puede |
113 ``etiquetar'' un parche con un \emph{guardia}, que simplemente es una | |
114 cadena de texto de su elección, y luego decirle a MQ que seleccione | |
115 guardias específicos para usar cuando aplique parches. MQ entonces | |
116 aplicará, u omitirá, un parche vigilado, dependiendo de los guardias | |
117 que usted haya seleccionado. | |
435 | 118 |
588 | 119 Un parche puede tener una cantidad arbitraria de guardias; cada uno es |
120 \emph{positivo} (``aplique el parche si este guardia es | |
121 seleccionado'') o \emph{negativo} (``omita este parche si este guardia | |
122 es seleccionado''). Un parche sin guardias siempre es aplicado. | |
435 | 123 |
589
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
124 \section{Controlar los guardias de un parche} |
435 | 125 |
590
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
126 %TODO tal vez no decir determinar, sino definir? |
589
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
127 El comando \hgxcmd{mq}{qguard} le permite determinar qué guardias |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
128 deben aplicarse a un parche, o mostrar los guardias que están en |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
129 efecto. Sin ningún argumento, el comando muestra los guardias del |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
130 parche actual de la parte más alta de la pila. |
435 | 131 \interaction{mq.guards.qguard} |
589
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
132 Para poner un guardia positivo en un parche, prefije el nombre del |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
133 guardia con un ``\texttt{+}''. |
435 | 134 \interaction{mq.guards.qguard.pos} |
589
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
135 Para poner un guardia negativo en un parche, prefije el nombre del |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
136 guardia con un ``\texttt{-}''. |
435 | 137 \interaction{mq.guards.qguard.neg} |
138 | |
139 \begin{note} | |
589
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
140 El comando \hgxcmd{mq}{qguard} \emph{pone} los guardias en un |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
141 parche; no los \emph{modifica}. Esto significa que si usted ejecuta |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
142 \hgcmdargs{qguard}{+a +b} sobre un parche, y luego |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
143 \hgcmdargs{qguard}{+c} en el mismo parche, el único guardia sobre el |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
144 parche después del comando será \texttt{+c}. |
435 | 145 \end{note} |
146 | |
589
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
147 Mercurial almacena los guardias en el fichero \sfilename{series}; la |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
148 forma en que son almacenados es fácil tanto de entender como de editar |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
149 a mano. (En otras palabras, usted no tiene que usar el comando |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
150 \hgxcmd{mq}{qguard} si no lo desea; está bien simplemente editar el |
254888ffaf0a
translated another section
Javier Rojas <jerojasro@devnull.li>
parents:
588
diff
changeset
|
151 fichero \sfilename{series}) |
435 | 152 \interaction{mq.guards.series} |
153 | |
590
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
154 \section{Selecccionar los guardias a usar} |
435 | 155 |
590
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
156 %TODO tal vez no decir determinar, sino definir? |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
157 El comando \hgxcmd{mq}{qselect} determina qué guardias están activos |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
158 en cualquier momento. El efecto de esto es determinar qué parches |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
159 aplicará MQ la próxima vez que usted ejecute \hgxcmd{mq}{qpush}. No |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
160 tiene ningún otro efecto; en particular, no hace nada a los parches |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
161 que ya han sido aplicados. |
435 | 162 |
590
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
163 Sin argumentos, el comando \hgxcmd{mq}{qselect} lista los guardias en |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
164 efecto actualmente, uno por cada línea de salida. Cada argumento es |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
165 tratado como el nombre de un guardia a aplicar. |
435 | 166 \interaction{mq.guards.qselect.foo} |
590
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
167 Si está interesado, los guardias seleccionados actualmente están |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
168 almacenados en el fichero \sfilename{guards}. |
435 | 169 \interaction{mq.guards.qselect.cat} |
590
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
170 Podemos ver el efecto que tienen los guardias seleccionados cuando |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
171 ejecutamos \hgxcmd{mq}{qpush}. |
435 | 172 \interaction{mq.guards.qselect.qpush} |
173 | |
590
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
174 Un guardia no puede empezar con un caracter ``\texttt{+}'' o |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
175 ``\texttt{-}''. El nombre del guardia no debe contener espacios en |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
176 blanco, pero muchos otros caracteres son aceptables. Si usted trata de |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
177 usar un guardia con un nombre inválido, MQ se quejará: |
435 | 178 \interaction{mq.guards.qselect.error} |
590
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
179 Cambiar los guardias seleccionados cambia los parches que son |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
180 aplicados. |
435 | 181 \interaction{mq.guards.qselect.quux} |
590
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
182 Usted puede ver en el ejemplo de abajo que los guardias negativos |
795f2964e104
translated section 13.4
Javier Rojas <jerojasro@devnull.li>
parents:
589
diff
changeset
|
183 tienen precedencia sobre los guardias positivos. |
435 | 184 \interaction{mq.guards.qselect.foobar} |
185 | |
186 \section{MQ's rules for applying patches} | |
187 | |
188 The rules that MQ uses when deciding whether to apply a patch | |
189 are as follows. | |
190 \begin{itemize} | |
191 \item A patch that has no guards is always applied. | |
192 \item If the patch has any negative guard that matches any currently | |
193 selected guard, the patch is skipped. | |
194 \item If the patch has any positive guard that matches any currently | |
195 selected guard, the patch is applied. | |
196 \item If the patch has positive or negative guards, but none matches | |
197 any currently selected guard, the patch is skipped. | |
198 \end{itemize} | |
199 | |
200 \section{Trimming the work environment} | |
201 | |
202 In working on the device driver I mentioned earlier, I don't apply the | |
203 patches to a normal Linux kernel tree. Instead, I use a repository | |
204 that contains only a snapshot of the source files and headers that are | |
205 relevant to Infiniband development. This repository is~1\% the size | |
206 of a kernel repository, so it's easier to work with. | |
207 | |
208 I then choose a ``base'' version on top of which the patches are | |
209 applied. This is a snapshot of the Linux kernel tree as of a revision | |
210 of my choosing. When I take the snapshot, I record the changeset ID | |
211 from the kernel repository in the commit message. Since the snapshot | |
212 preserves the ``shape'' and content of the relevant parts of the | |
213 kernel tree, I can apply my patches on top of either my tiny | |
214 repository or a normal kernel tree. | |
215 | |
216 Normally, the base tree atop which the patches apply should be a | |
217 snapshot of a very recent upstream tree. This best facilitates the | |
218 development of patches that can easily be submitted upstream with few | |
219 or no modifications. | |
220 | |
221 \section{Dividing up the \sfilename{series} file} | |
222 | |
223 I categorise the patches in the \sfilename{series} file into a number | |
224 of logical groups. Each section of like patches begins with a block | |
225 of comments that describes the purpose of the patches that follow. | |
226 | |
227 The sequence of patch groups that I maintain follows. The ordering of | |
228 these groups is important; I'll describe why after I introduce the | |
229 groups. | |
230 \begin{itemize} | |
231 \item The ``accepted'' group. Patches that the development team has | |
232 submitted to the maintainer of the Infiniband subsystem, and which | |
233 he has accepted, but which are not present in the snapshot that the | |
234 tiny repository is based on. These are ``read only'' patches, | |
235 present only to transform the tree into a similar state as it is in | |
236 the upstream maintainer's repository. | |
237 \item The ``rework'' group. Patches that I have submitted, but that | |
238 the upstream maintainer has requested modifications to before he | |
239 will accept them. | |
240 \item The ``pending'' group. Patches that I have not yet submitted to | |
241 the upstream maintainer, but which we have finished working on. | |
242 These will be ``read only'' for a while. If the upstream maintainer | |
243 accepts them upon submission, I'll move them to the end of the | |
244 ``accepted'' group. If he requests that I modify any, I'll move | |
245 them to the beginning of the ``rework'' group. | |
246 \item The ``in progress'' group. Patches that are actively being | |
247 developed, and should not be submitted anywhere yet. | |
248 \item The ``backport'' group. Patches that adapt the source tree to | |
249 older versions of the kernel tree. | |
250 \item The ``do not ship'' group. Patches that for some reason should | |
251 never be submitted upstream. For example, one such patch might | |
252 change embedded driver identification strings to make it easier to | |
253 distinguish, in the field, between an out-of-tree version of the | |
254 driver and a version shipped by a distribution vendor. | |
255 \end{itemize} | |
256 | |
257 Now to return to the reasons for ordering groups of patches in this | |
258 way. We would like the lowest patches in the stack to be as stable as | |
259 possible, so that we will not need to rework higher patches due to | |
260 changes in context. Putting patches that will never be changed first | |
261 in the \sfilename{series} file serves this purpose. | |
262 | |
263 We would also like the patches that we know we'll need to modify to be | |
264 applied on top of a source tree that resembles the upstream tree as | |
265 closely as possible. This is why we keep accepted patches around for | |
266 a while. | |
267 | |
268 The ``backport'' and ``do not ship'' patches float at the end of the | |
269 \sfilename{series} file. The backport patches must be applied on top | |
270 of all other patches, and the ``do not ship'' patches might as well | |
271 stay out of harm's way. | |
272 | |
273 \section{Maintaining the patch series} | |
274 | |
275 In my work, I use a number of guards to control which patches are to | |
276 be applied. | |
277 | |
278 \begin{itemize} | |
279 \item ``Accepted'' patches are guarded with \texttt{accepted}. I | |
280 enable this guard most of the time. When I'm applying the patches | |
281 on top of a tree where the patches are already present, I can turn | |
282 this patch off, and the patches that follow it will apply cleanly. | |
283 \item Patches that are ``finished'', but not yet submitted, have no | |
284 guards. If I'm applying the patch stack to a copy of the upstream | |
285 tree, I don't need to enable any guards in order to get a reasonably | |
286 safe source tree. | |
287 \item Those patches that need reworking before being resubmitted are | |
288 guarded with \texttt{rework}. | |
289 \item For those patches that are still under development, I use | |
290 \texttt{devel}. | |
291 \item A backport patch may have several guards, one for each version | |
292 of the kernel to which it applies. For example, a patch that | |
293 backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard. | |
294 \end{itemize} | |
295 This variety of guards gives me considerable flexibility in | |
296 qdetermining what kind of source tree I want to end up with. For most | |
297 situations, the selection of appropriate guards is automated during | |
298 the build process, but I can manually tune the guards to use for less | |
299 common circumstances. | |
300 | |
301 \subsection{The art of writing backport patches} | |
302 | |
303 Using MQ, writing a backport patch is a simple process. All such a | |
304 patch has to do is modify a piece of code that uses a kernel feature | |
305 not present in the older version of the kernel, so that the driver | |
306 continues to work correctly under that older version. | |
307 | |
308 A useful goal when writing a good backport patch is to make your code | |
309 look as if it was written for the older version of the kernel you're | |
310 targeting. The less obtrusive the patch, the easier it will be to | |
311 understand and maintain. If you're writing a collection of backport | |
312 patches to avoid the ``rat's nest'' effect of lots of | |
313 \texttt{\#ifdef}s (hunks of source code that are only used | |
314 conditionally) in your code, don't introduce version-dependent | |
315 \texttt{\#ifdef}s into the patches. Instead, write several patches, | |
316 each of which makes unconditional changes, and control their | |
317 application using guards. | |
318 | |
319 There are two reasons to divide backport patches into a distinct | |
320 group, away from the ``regular'' patches whose effects they modify. | |
321 The first is that intermingling the two makes it more difficult to use | |
322 a tool like the \hgext{patchbomb} extension to automate the process of | |
323 submitting the patches to an upstream maintainer. The second is that | |
324 a backport patch could perturb the context in which a subsequent | |
325 regular patch is applied, making it impossible to apply the regular | |
326 patch cleanly \emph{without} the earlier backport patch already being | |
327 applied. | |
328 | |
329 \section{Useful tips for developing with MQ} | |
330 | |
331 \subsection{Organising patches in directories} | |
332 | |
333 If you're working on a substantial project with MQ, it's not difficult | |
334 to accumulate a large number of patches. For example, I have one | |
335 patch repository that contains over 250 patches. | |
336 | |
337 If you can group these patches into separate logical categories, you | |
338 can if you like store them in different directories; MQ has no | |
339 problems with patch names that contain path separators. | |
340 | |
341 \subsection{Viewing the history of a patch} | |
342 \label{mq-collab:tips:interdiff} | |
343 | |
344 If you're developing a set of patches over a long time, it's a good | |
345 idea to maintain them in a repository, as discussed in | |
346 section~\ref{sec:mq:repo}. If you do so, you'll quickly discover that | |
347 using the \hgcmd{diff} command to look at the history of changes to a | |
348 patch is unworkable. This is in part because you're looking at the | |
349 second derivative of the real code (a diff of a diff), but also | |
350 because MQ adds noise to the process by modifying time stamps and | |
351 directory names when it updates a patch. | |
352 | |
353 However, you can use the \hgext{extdiff} extension, which is bundled | |
354 with Mercurial, to turn a diff of two versions of a patch into | |
355 something readable. To do this, you will need a third-party package | |
356 called \package{patchutils}~\cite{web:patchutils}. This provides a | |
357 command named \command{interdiff}, which shows the differences between | |
358 two diffs as a diff. Used on two versions of the same diff, it | |
359 generates a diff that represents the diff from the first to the second | |
360 version. | |
361 | |
362 You can enable the \hgext{extdiff} extension in the usual way, by | |
363 adding a line to the \rcsection{extensions} section of your \hgrc. | |
364 \begin{codesample2} | |
365 [extensions] | |
366 extdiff = | |
367 \end{codesample2} | |
368 The \command{interdiff} command expects to be passed the names of two | |
369 files, but the \hgext{extdiff} extension passes the program it runs a | |
370 pair of directories, each of which can contain an arbitrary number of | |
371 files. We thus need a small program that will run \command{interdiff} | |
372 on each pair of files in these two directories. This program is | |
373 available as \sfilename{hg-interdiff} in the \dirname{examples} | |
374 directory of the source code repository that accompanies this book. | |
375 \excode{hg-interdiff} | |
376 | |
377 With the \sfilename{hg-interdiff} program in your shell's search path, | |
378 you can run it as follows, from inside an MQ patch directory: | |
379 \begin{codesample2} | |
380 hg extdiff -p hg-interdiff -r A:B my-change.patch | |
381 \end{codesample2} | |
382 Since you'll probably want to use this long-winded command a lot, you | |
383 can get \hgext{hgext} to make it available as a normal Mercurial | |
384 command, again by editing your \hgrc. | |
385 \begin{codesample2} | |
386 [extdiff] | |
387 cmd.interdiff = hg-interdiff | |
388 \end{codesample2} | |
389 This directs \hgext{hgext} to make an \texttt{interdiff} command | |
390 available, so you can now shorten the previous invocation of | |
391 \hgxcmd{extdiff}{extdiff} to something a little more wieldy. | |
392 \begin{codesample2} | |
393 hg interdiff -r A:B my-change.patch | |
394 \end{codesample2} | |
395 | |
396 \begin{note} | |
397 The \command{interdiff} command works well only if the underlying | |
398 files against which versions of a patch are generated remain the | |
399 same. If you create a patch, modify the underlying files, and then | |
400 regenerate the patch, \command{interdiff} may not produce useful | |
401 output. | |
402 \end{note} | |
403 | |
404 The \hgext{extdiff} extension is useful for more than merely improving | |
405 the presentation of MQ~patches. To read more about it, go to | |
406 section~\ref{sec:hgext:extdiff}. | |
407 | |
408 %%% Local Variables: | |
409 %%% mode: latex | |
410 %%% TeX-master: "00book" | |
411 %%% End: |