hgbook
view es/branch.tex @ 539:ac83a9624252
updated project status
author | Javier Rojas <jerojasro@devnull.li> |
---|---|
date | Tue Jan 27 22:30:58 2009 -0500 (2009-01-27) |
parents | 871a245975e4 |
children |
line source
1 %% vim: tw=70 encoding=utf8
2 \chapter{Administración de versiones y desarrollo ramificado}
3 \label{chap:branch}
5 Mercurial ofrece varios mecanismos que le permiten administrar un
6 proyecto que avanza en múltiples frentes simultáneamente. Para
7 entender estos mecanismos, demos un vistazo a la estructura usual de
8 un proyecto de software.
10 Muchos proyectos de software liberan una versión ``mayor'' que contiene
11 nuevas características substanciales. En paralelo, pueden liberar
12 versiones ``menores''. Usualmente éstas son idénticas a las
13 versiones mayores en las cuales están basadas, pero con arreglos para
14 algunos fallos.
16 En este capítulo, comenzaremos hablando de cómo mantener registro de
17 etapas del proyecto como las liberaciones de una
18 versión. Continuaremos hablando del flujo de trabajo entre las
19 diferentes fases de un proyecto, y cómo puede ayudar Mercurial a
20 aislar y administrar tal trabajo.
22 \section{Dar un nombre persistente a una revisión}
24 Cuando usted decide otorgar a una revisión el nombre particular de una
25 ``versión'', es buena idea grabar la identidad de tal revisión.
26 Esto le permitirá reproducir dicha versión en una fecha posterior,
27 para cualquiera que sea el
28 propósito que se tenga en ese momento (reproducir un fallo, portar
29 a una nueva plataforma, etc).
30 \interaction{tag.init}
32 Mercurial le permite dar un nombre permanente a cualquier revisión
33 usando la orden \hgcmd{tag}. Sin causa de sorpresa, esos nombres se llaman
34 ``tags'' (etiquetas).
35 \interaction{tag.tag}
37 Una etiqueta no es más que un ``nombre simbólico'' para una revisión. Las
38 etiquetas existen únicamente para su conveniencia, brindándole una forma
39 permanente y sencilla de referirse a una revisión; Mercurial no
40 interpreta de ninguna manera los nombres de las etiquetas que usted use.
41 Mercurial tampoco impone restricción alguna al nombre de una etiqueta, más
42 allá de lo necesario para asegurar que una etiqueta pueda procesarse sin
43 ambigüedades. El nombre de una etiqueta no puede tener ninguno de los
44 siguientes caracteres:
45 \begin{itemize}
46 \item Dos puntos (ASCII 58, ``\texttt{:}'')
47 \item Retorno de carro (return) (ASCII 13, ``\Verb+\r+'')
48 \item Nueva línea (ASCII 10, ``\Verb+\n+'')
49 \end{itemize}
51 Puede usar la orden \hgcmd{tags} para ver las etiquetas presentes en
52 su repositorio. Al desplegarse, cada revisión marcada se identifica
53 primero con su nombre, después con el número de revisión y finalmente con
54 un hash único de la revisión.
55 \interaction{tag.tags}
56 Note que \texttt{tip} aparece en en listado generado por \hgcmd{tags}. La etiqueta
57 \texttt{tip} es una etiqueta ``flotante'' especial, que identifica siempre
58 la revisión más reciente en el repositorio.
60 Al desplegar la orden \hgcmd{tags}, las etiquetas se listan en orden
61 inverso, por número de revisión. Lo que significa usualmente que las
62 etiquetas más recientes se listan antes que las más antiguas. También
63 significa que la etiqueta \texttt{tip} siempre aparecerá como primera
64 etiqueta listada al desplegar la orden \hgcmd{tags}.
66 Cuando usted ejecuta \hgcmd{log}, si se muestra una revisión que tenga
67 etiquetas asociadas a ella, se imprimirán tales etiquetas.
68 \interaction{tag.log}
70 Siempre que requiera indicar un~ID de revisión a una orden de
71 Mercurial, aceptará un nombre de etiqueta en su lugar. Internamente,
72 Mercurial traducirá su nombre de etiqueta en el~ID de revisión
73 correspondiente, y lo usará.
74 \interaction{tag.log.v1.0}
76 No hay límites en la cantidad de etiquetas por repositorio, o la cantidad
77 de etiquetas que una misma revisión pueda tener. Siendo prácticos, no es
78 muy buena idea tener ``demasiadas'' (la cantidad variará de un
79 proyecto a otro), debido a que la intención es ayudarle a encontrar
80 revisiones. Si tiene demasiadas etiquetas, la facilidad de usarlas
81 para identificar revisiones disminuirá rápidamente.
83 Por ejemplo, si su proyecto tiene etapas (milestones) frecuentes, de pocos
84 días, es perfectamente razonable asignarle una etiqueta a cada una de
85 ellas. Pero si tiene un sistema de construcción automática de binarios
86 que asegura que cada revisión puede generarse limpiamente, estaría
87 introduciendo mucho ruido si se usara una etiqueta para cada generación
88 exitosa. Más bien, podría usar tags para generaciones fallidas
89 (\textexclamdown en
90 caso de que estas sean raras!), o simplemente evitar las etiquetas para
91 llevar cuenta de la posibilidad de generación de binarios.
94 Si quiere eliminar una etiqueta que no desea, use
95 \hgcmdargs{tag}{--remove}.
96 \interaction{tag.remove}
97 También puede modificar una etiqueta en cualquier momento, para que
98 identifique una revisión distinta, simplemente usando una nueva orden
99 \hgcmd{tag}. Deberá usar la opción \hgopt{tag}{-f} para indicarle a
100 Mercurial que \emph{realmente} desea actualizar la etiqueta.
101 \interaction{tag.replace}
102 De todas maneras habrá un registro permanente de la antigua identidad
103 de la etiqueta, pero Mercurial no la usará. Por lo tanto no hay
104 problema al marcar con una etiqueta una revisión incorrecta; lo único
105 que debe hacer es mover la etiqueta hacia la revisión correcta tan
106 pronto como localice el error.
108 Mercurial almacena las etiquetas en un fichero controlado por revisiones en
109 su repositorio. Si ha creado etiquetas, las encontrará en un fichero
110 llamado \sfilename{.hgtags}. Cuando invoca la orden \hgcmd{tag},
111 Mercurial modifica este fichero, y hace la consignación del cambio al
112 mismo automáticamente. Esto significa que cada vez que ejecuta
113 \hgcmd{tag}, verá un conjunto de cambios correspondiente en la salida
114 de \hgcmd{log}.
115 \interaction{tag.tip}
117 \subsection{Manejo de conflictos entre etiquetas durante una fusión}
119 Usualmente no tendrá que preocuparse por el fichero \sfilename{.hgtags},
120 pero a veces hace su aparición durante una fusión. El formato del
121 fichero es sencillo: Consiste de una serie de líneas. Cada línea
122 comienza con un hash de conjunto de cambios, seguido por un espacio,
123 seguido por el nombre de una etiqueta.
125 Si está resolviendo un conflicto en el fichero \sfilename{.hgtags}
126 durante una fusión, hay un detalle para tener en cuenta al modificar
127 el fichero \sfilename{.hgtags}:
128 cuando Mercurial procesa las etiquetas en el repositorio, \emph{nunca}
129 lee la copia de trabajo del fichero \sfilename{.hgtags}. En cambio,
130 lee la versión \emph{consignada más reciente} del fichero.
132 Una consecuencia desafortunada de este diseño es que usted no puede
133 verificar que su fichero \sfilename{.hgtags} fusionado sea correcto hasta
134 \emph{después} de haber consignado un cambio. Así que si se
135 encuentra resolviendo un conflicto en \sfilename{.hgtags} durante una
136 fusión, asegúrese de ejecutar la orden \hgcmd{tags} después de
137 consignar. Si encuentra un error en el fichero \sfilename{.hgtags},
138 la orden reportará el lugar del error, que podrá arreglar y después
139 consignar. Posteriormente ejecute de nuevo la orden \hgcmd{tags} para
140 asegurarse de que su arreglo fue aplicado correctamente .
142 \subsection{Etiquetas y clonado}
144 Puede haber notado que la orden \hgcmd{clone} tiene la opción
145 \hgopt{clone}{-r} que le permite clonar una copia exacta del
146 repositorio hasta un conjunto de cambios específico. El nuevo clon no
147 tendrá historial posterior a la revisión que usted haya
148 especificado. Esto tiene una interacción con etiquetas que puede
149 sorprender a los desprevenidos.
151 Recuerde que una etiqueta se almacena como una revisión al fichero
152 \sfilename{.hgtags}, así que cuando usted crea una etiqueta, el
153 conjunto de cambios en el cual ésta se almacena necesariamente se
154 refiere a un conjunto de cambios anterior. Cuando ejecuta
155 \hgcmdargs{clone}{-r foo} para clonar un repositorio hasta la etiqueta
156 \texttt{foo}, el nuevo clon \emph{no contendrá el historial que creo
157 la etiqueta} que usó para clonar el repositorio. El resultado es que tendrá
158 exactamente el subconjunto correcto del historial del proyecto en el
159 nuevo repositorio, pero, \emph{no} la etiqueta que podría haber esperado.
161 \subsection{Cuando las etiquetas permanentes son demasiado}
163 Dado que las etiquetas de Mercurial están controladas por revisiones y se
164 llevan en el historial del proyecto, todas las personas involucradas
165 verán las etiquetas que usted haya creado. El hecho de dar nombres a las
166 revisiones tiene usos más allá que simplemente hacer notar que la
167 revisión \texttt{4237e45506ee} es realmente \texttt{v2.0.2}. Si está
168 tratando de encontrar un fallo sutil, posiblemente desearía colocar una
169 etiqueta recordándole algo como ``Ana vio los síntomas en esta revisión''.
171 Para estos casos, lo que usted posiblemente desearía serían etiquetas
172 \emph{locales}. Puede crear una etiqueta local con la opción~\hgopt{tag}{-l}
173 de la orden \hgcmd{tag}. Esto guardará la etiqueta en un fichero llamado
174 \sfilename{.hg/localtags}. A diferencia de \sfilename{.hgtags},
175 \sfilename{.hg/localtags} no está controlado por revisiones.
176 Cualquier etiqueta que usted cree usando \hgopt{tag}{-l} se mantendrá
177 local al repositorio en el que esté trabajando en ese momento.
179 \section{El flujo de cambios---El gran cuadro vs. el pequeño}
181 Retomando lo mencionado en el comienzo de un capítulo, pensemos en el
182 hecho de que un proyecto tiene muchas piezas concurrentes de trabajo
183 en desarrollo al mismo tiempo.
185 Puede haber prisa por una nueva versión ``principal''; una nueva
186 versión con un arreglo de fallo a la última versión; y una versión de
187 ``mantenimiento correctivo'' a una versión antigua que ha entrado en
188 modo de mantenimiento.
190 Usualmente la gente se refiere a esas direcciones
191 concurrentes de desarrollo como ``ramas''. Sin embargo, ya hemos visto que
192 en varias ocasiones Mercurial trata a \emph{todo el historial} como
193 una serie de ramas y fusiones. Realmente lo que tenemos aquí es dos
194 ideas que se relacionan periféricamente, pero que en esencia comparten
195 un nombre.
196 \begin{itemize}
197 \item ``El gran cuadro'' Las ramas representan un barrido de la
198 evolución del proyecto; la gente les da nombres y hablan acerca de
199 ellas en sus conversaciones.
200 \item ``El cuadro pequeño'' Las ramas son artefactos de las
201 actividades diarias de desarrollar y fusionar cambios. Exponen la
202 narrativa de cómo se desarrolló el código.
203 \end{itemize}
205 \section{Administrar ramas en repositorios estilo gran cuadro}
207 En Mercurial la forma más sencilla de aislar una rama del ``gran
208 cuadro'' es a través de un repositorio dedicado. Si cuenta con un
209 repositorio compartido existente ---llamémoslo
210 \texttt{myproject}---que alcanzó la etapa ``1.0'', puede comenzar a
211 prepararse para versiones de mantenimiento futuras a partir de la
212 versión~1.0 marcando con una etiqueta la revisión con la cual preparó la versión~1.0.
213 \interaction{branch-repo.tag}
214 Ahora puede clonar un repositorio compartido nuevo
215 \texttt{myproject-1.0.1} con tal etiqueta.
216 \interaction{branch-repo.clone}
218 Posteriormente, si alguien necesita trabajar en la reparación de un
219 fallo debería dirigirse a la liberación de versión~1.0.1 que viene en
220 camino, ellos clonarían el repositorio \texttt{myproject-1.0.1},
221 harían sus cambios y los empujarían de vuelta.
222 \interaction{branch-repo.bugfix}
223 Mientras tanto, el desarrollo para la siguiente versión mayor puede
224 continuar aislado e incólume, en el repositorio \texttt{myproject}.
225 \interaction{branch-repo.new}
227 \section{No repita trabajo: fusión entre ramas}
229 En muchos casos, cuando tiene un fallo para arreglar en una rama de
230 mantenimiento, es muy probable que el fallo también esté en la rama
231 principal (y posiblemente en otras ramas de mantenimiento
232 también). Solamente un desarrollador extraño desearía corregir el
233 mismo fallo muchas veces, por tanto, veremos varias alternativas con
234 las que Mercurial puede ayudarle a administrar tales arreglos de fallo
235 sin duplicar su trabajo.
237 En el caso más sencillo, basta con jalar los cambios de la rama de
238 mantenimiento a la rama objetivo en su clon local.
239 \interaction{branch-repo.pull}
240 A continuación deberá mezclar las cabezas de las dos ramas, y empujar
241 de nuevo a la rama principal.
242 \interaction{branch-repo.merge}
244 \section{Nombrar ramas dentro de un repositorio}
246 La aproximación correcta en casi todas las oportunidades es aislar las
247 ramas en los repositorios. Es fácil de entender gracias a su
248 simplicidad; y es difícil cometer errores. Hay una relación uno a uno
249 entre las ramas y los directorios con los que está trabajando en su
250 sistema. Esto le permite usar emplear herramientas usuales (que no son
251 conscientes de Mercurial) para trabajar con los ficheros dentro de una
252 rama/repositorio.
254 Si se encuentra más en la categoría ``usuario diestro'' (\emph{y} sus
255 colaboradores también), puede considerar otra alternativa para
256 administrar las ramas. He mencionado con anterioridad la distinción a
257 nivel humano entre las ramas estilo ``cuadro pequeño'' y ``gran
258 cuadro''. Mientras que Mercurial trabaja con muchas ramas del estilo
259 ``cuadro pequeño'' en el repositorio todo el tiempo (por ejemplo cuando
260 usted jala cambios, pero antes de fusionarlos), \emph{también} puede
261 trabajar con varias ramas del ``cuadro grande''.
263 El truco para trabajar de esta forma en Mercurial se logra gracias a
264 que puede asignar un \emph{nombre} persistente a una rama. Siempre
265 existe una rama llamada \texttt{default}. Incluso antes de que
266 empiece a nombrar ramas por su cuenta, puede encontrar indicios de la
267 rama \texttt{default} si los busca.
269 Por ejemplo, cuando invoca la orden \hgcmd{commit}, y se lanza su
270 editor para introducir el mensaje de la consignación, busque la línea
271 que contiene el texto ``\texttt{HG: branch default}'' al final. Le
272 está indicando que su consignación ocurrirá en la rama llamada
273 \texttt{default}.
275 Use la orden \hgcmd{branches} para empezar a trabajar con ramas
276 nombradas. Esta orden mostrará las ramas presentes en su repositorio,
277 indicándole qué conjunto de cambios es la punta de cada una.
278 \interaction{branch-named.branches}
279 Dado que todavía no ha creado ramas nombradas, la única que verá será
280 \texttt{default}.
282 Para hallar cuál es la rama ``actual'', invoque la orden
283 \hgcmd{branch}, sin argumento alguno. Le informará en qué rama se
284 encuentra el padre del conjunto de cambios actual.
285 \interaction{branch-named.branch}
287 Para crear una nueva rama, invoque la orden \hgcmd{branch} de
288 nuevo. En esta oportunidad, ofrezca un argumento: el nombre de la rama
289 que desea crear.
290 \interaction{branch-named.create}
292 Después de crear la rama, usted podría desear ver el efecto que tuvo
293 la orden \hgcmd{branch}. ¿Qué reportan las ordenes \hgcmd{status} y
294 \hgcmd{tip}?
295 \interaction{branch-named.status}
296 Nada cambia en el directorio actual, y no se ha añadido nada al
297 historial. Esto sugiere que al ejecutar la orden \hgcmd{branch} no hay
298 un efecto permanente; solamente le indica a que nombre de rama usará
299 la \emph{próxima} vez que consigne un conjunto de cambios.
301 Cuando consigna un cambio, Mercurial almacena el nombre de la rama en
302 la cual consignó. Una vez que haya cambiado de la rama \texttt{default}
303 y haya consignado, verá que el nombre de la nueva rama se mostrará
304 cuando use la orden \hgcmd{log}, \hgcmd{tip}, y otras órdenes que
305 desplieguen la misma clase de información.
306 \interaction{branch-named.commit}
307 Las órdenes del tipo \hgcmd{log} imprimirán el nombre de la rama de
308 cualquier conjunto de cambios que no esté en la rama
309 \texttt{default}. Como resultado, si nunca usa ramas nombradas, nunca
310 verá esta información.
312 Una vez que haya nombrado una rama y consignado un cambio con ese
313 nombre, todas las consignaciones subsecuentes que desciendan de ese
314 cambio heredarán el mismo nombre de rama. Puede cambiar el nombre de
315 una rama en cualquier momento con la orden \hgcmd{branch}.
316 \interaction{branch-named.rebranch}
317 Esto es algo que no hará muy seguido en la práctica, debido que los
318 nombres de las ramas tienden a tener vidas largas. (Esto no es una
319 regla, solamente una observación.)
321 \section{Tratamiento de varias ramas nombradas en un repositorio}
323 Si tiene más de una rama nombrada en un repositorio, Mercurial
324 recordará la rama en la cual está su directorio de trabajo cuando
325 invoque una orden como \hgcmd{update} o \hgcmdargs{pull}{-u}. Se
326 actualizará su directorio de trabajo actual a la punta de esta rama, sin
327 importar cuál sea la punta ``a lo largo del repositorio''. Para
328 actualizar a una revisión que está en una rama con distinto nombre,
329 puede necesitar la opción \hgopt{update}{-C} de \hgcmd{update}.
331 Este comportamiento puede ser sutil, así que veámoslo en acción. Primero,
332 recordemos en qué rama estamos trabajando, y qué ramas están en
333 nuestro repositorio.
334 \interaction{branch-named.parents}
335 Estamos en la rama \texttt{bar}, pero existe otra rama más antigua
336 llamada \hgcmd{foo}.
338 Podemos hacer \hgcmd{update} entre los tipos de las ramas \texttt{foo}
339 y \texttt{bar} sin necesidad de usar la opción \hgopt{update}{-C},
340 puesto que esto solamente implica ir linealmente hacia adelante y
341 atrás en nuestro historial de cambios.
342 \interaction{branch-named.update-switchy}
344 Si volvemos a la rama \texttt{foo} e invocamos la orden \hgcmd{update},
345 nos mantendrá en \texttt{foo}, sin movernos a la punta de \texttt{bar}.
346 \interaction{branch-named.update-nothing}
348 Al consignar un cambio a la rama \texttt{foo} se introducirá una nueva
349 cabeza.
350 \interaction{branch-named.foo-commit}
352 \section{Nombres de ramas y fusiones}
354 Posiblemente ha notado que las fusiones en Mercurial no son simétricas.
355 Supongamos que su repositorio tiene dos cabezas, 17 y 23. Si yo invoco
356 \hgcmd{update} a 17 y aplico \hgcmd{merge} a 23, Mercurial almacena 17
357 como el primer padre de la fusión, y 23 como el segundo. Mientras que
358 si hago \hgcmd{update} a 23 y después aplico \hgcmd{merge} con 17,
359 grabará a 23 como el primer padre, y 17 como el segundo.
361 Esto afecta el cómo elige Mercurial el nombre de la rama cuando usted
362 hace la fusión. Después de una fusión, Mercurial mantendrá el nombre de la
363 rama del primer padre cuando consigne el resultado de la fusión. Si
364 el primer nombre de su padre es \texttt{foo}, y fusiona con
365 \texttt{bar}, el nombre de la rama continuará siendo \texttt{foo}
366 después de fusionar.
368 No es inusual que un repositorio contenga varias cabezas, cada una con
369 el mismo nombre de rama. Digamos que estoy trabajando en la rama
370 \texttt{foo}, y usted también. Consignamos cambios distintos; yo jalo
371 sus cambios; Ahora tengo dos cabezas, cada una afirmando estar en la
372 rama \texttt{foo}. El resultado de una fusión será una única cabeza
373 en la rama \texttt{foo} como usted esperaría.
375 Pero si estoy trabajando en la rama \texttt{bar}, y fusiono el trabajo
376 de la rama \texttt{foo}, el resultado permanecerá en la rama
377 \texttt{bar}.
378 \interaction{branch-named.merge}
380 En un ejemplo más concreto, si yo estoy trabajando en la rama
381 \texttt{bleeding-edge}, y deseo traer los arreglos más recientes de la
382 rama \texttt{estable}, Mercurial elegirá el nombre de rama ``correcto''
383 (\texttt{bleeding-edge}) cuando yo jale una fusión desde \texttt{estable}.
385 \section{Normalmente es útil nombrar ramas}
387 No debería considerar que las ramas nombradas son aplicables
388 únicamente en situaciones con muchas ramas de larga vida cohabitando
389 en un mismo repositorio. Son muy útiles incluso en los casos de
390 una rama por repositorio.
392 En el caso más sencillo, dar un nombre a cada rama ofrece un registro
393 permanente acerca de en qué conjunto de cambios se generó la rama.
394 Esto le ofrece más contexto cuando esté tratando de seguir el
395 historial de un proyecto ramificado de larga vida.
397 Si está trabajando con repositorios compartidos, puede configurar el gancho
398 \hook{pretxnchangegroup} para que cada uno bloquee los cambios con
399 nombres de rama ``incorrectos'' que están por adicionarse. Este
400 provee una defensa sencilla, pero efectiva, para evitar que la gente
401 publique accidentalmente cambios de una rama ``super nueva'' a la rama
402 ``estable''. Tal gancho podría verse de la siguiente forma dentro de
403 un repositorio compartido de \hgrc.
404 \begin{codesample2}
405 [hooks]
406 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch
407 \end{codesample2}
409 %%% Local Variables:
410 %%% mode: latex
411 %%% TeX-master: "00book"
412 %%% End: