view es/branch.tex @ 430:3502b859cfe4

Minor advance on branches chapter

\chapter{Administración de Versiones y desarrollo ramificado}
\label{chap:branch}

Mercurial ofrece varios mecanismos que le permitirán administrar un
proyecto que avanza en múltiples frentes simultáneamente. Para
entender estos mecanismos, demos un vistazo a la estructura usual de
un proyecto de software.

Muchos proyectos de software liberan una versión``mayor'' que contiene
nuevas características substanciales.  En paralelo, pueden liberar
versiones ``menores''.   Estas usualmente son idénticas a las
versiones mayores en las cuales están basadas, pero con arreglo de
algunos fallos.

En este capítulo, comenzaremos hablando de cómo mantener registro de
las etapas del proyecto como las liberaciones de una
versión. Continuaremos hablando del flujo de trabajo entre las
diferentes fases de un proyecto, y como puede ayudar Mercurial a
independizar y administrar tal trabajo.

\section{Dar un nombre persistente a una revisión}

Cuando se decide a otorgar a una revisión el nombre particular de una
``versión'', es buena idea grabar la identidad para tal revisión.
Lo cual permitirá reproducir tal versión en una fecha posterior, o el
propósito que se considere en ese momento (reproducir un fallo, portar
a una nueva plataforma, etc).
\interaction{tag.init}

Mercurial le permite dar un nombre permanente a cualquier revisión
usando la orden \hgcmd{tag}.  Sin causa de sorpresa, esos nombres se llaman
``tags''(etiquetas).
\interaction{tag.tag}

Un tag no es más que un ``nombre simbólico'' para una revisión.  Los
tags existen únicamente para su conveniencia, dotándolo de una forma
permanente y sencilla para referirse a una revisión; Mercurial no
interpreta de ninguna manera los nombres de los tags que usted use.
Mercurial tampoco impone restricción alguna al nombre de un tag, más
allá de lo necesario para asegurar que un tag puede parsearse sin
ambigüedades. El nombre de un tag no puede tener ninguno de los
caracteres siguientes:
\begin{itemize}
\item Dos puntos (ASCII 58, ``\texttt{:}'')
\item Retroceso (return) (ASCII 13, ``\Verb+\r+'')
\item Nueva línea (ASCII 10, ``\Verb+\n+'')
\end{itemize}

Puede usar la orden \hgcmd{tags} para observar los tags presentes en
su repositorio. Al desplegarse, cada revisión marcada se identifica
primero con su nombre, después el número de revisión y finalmente con
un hash único de la revisión.
\interaction{tag.tags}
Note que \texttt{tip} aparece en la lista de \hgcmd{tags}.  El tag
\texttt{tip} es un tag ``flotante'' especial, que identifica siempre
la revisión más nueva en el repositorio.

Al desplegar la orden \hgcmd{tags}, los tags se listan en orden
inverso, por número de revisión. Lo que significa usualmente que los
tags más recientes se listan antes que los más antiguos. También
significa que el tag \texttt{tip} siempre aparecerá como primer tag
listado al desplegar la orden \hgcmd{tags}.

Cuando ejecuta \hgcmd{log}, se desplegará la revisión que tenga los
tags asociados a ella, se imprimirán tales tags.
\interaction{tag.log}

Siempre que requiera indicar un ~ID de revisión a una Orden de
Mercurial, aceptará un nombre de tag en su lugar.  Internamente,
Mercurial traducirá su nombre de tag en el ~ID de revisión
correspondiente, y lo usará.
\interaction{tag.log.v1.0}

No hay límites en la cantidad de tags por reposirorio, o la cantidad
de tags que una misma revisión pueda tener. Siendo prácticos, no es
muy buena idea tener ``demasiados'' (la cantidad variará de un
proyecto a otro), debido a que la intención es ayudarle a encontrar
revisiones. Si tiene demasiados tags, la facilidad para identificar
revisiones disminuirá rápidamente.

Por ejemplo, si su proyecto tiene etapas(milestones) frecuentes en pocos
días, es perfectamente razonable asignarle un tag a cada una de
ellas. Pero si tiene un sistema de construcción automática de binarios
que asegura que cada revisión puede generarse limpiamente, estaría
introduciendo mucho ruido si se usara un tag para cada generación
exitosa. Más bien, podría usar tags para generaciones fallidas (en
caso de que estas sean raras!), o simplemente evitar los tags para
llevar cuenta de la posibilidad de generación de binarios.


Si desea eliminar un tag que no desea, use
\hgcmdargs{tag}{--remove}.  
\interaction{tag.remove}
También puede modificar un tag en cualquier momento para que
identifique una revisión distinta, basta con aplicar una nueva orden
\hgcmd{tag}. Deberá usar la opción \hgopt{tag}{-f} para indicarle a
Mercurial que desea actualizar el tag \emph{en serio}.
\interaction{tag.replace}
De todas maneras habrá un registro permanente de la antigua identidad
del tag, pero Mercurial no la usará. Por lo tanto no hay castigo al
marcar con un tag una revisión incorrecta; lo único que debe hacer es
mover el tag hacia la revisión correcta tan pronto como localice el
error.

Mercurial almacena los tags en un archivo controlado por revisiones en
su repositorio. Si ha creado tags, los encontrará en un archivo
llamado \sfilename{.hgtags}.  Cuando invoca la orden \hgcmd{tag},
Mercurial modifica este archivo, y automáticamente hace commit del
cambio al mismo.  Esto significa que cada vez que ejecuta \hgcmd{tag},
verá el conjunto de cambios correspondiente en la salida de \hgcmd{log}.
\interaction{tag.tip}

\subsection{Manejo de conflictos entre tags durante una fusión}

Es usual no tener que preocuparse por el archivo \sfilename{.hgtags},
pero aveces hace su aparición durante una fusión. El formato del
archivo es sencillo: Consiste de una serie de líneas. Cada línea
comienza con un hash de Conjunto de Cambios, seguido por un espacio,
seguido por el nombre de un tag.

Si está resolviendo un conflicto en el archivo \sfilename{.hgtags}
durante una fusión, hay un detalle para tener en cuenta al modificar
el archivo \sfilename{.hgtags}:
cuando Mercurial parsea los tags en el repositorio \emph{nunca}
lee la copia de trabajo del archivo \sfilename{.hgtags}.  En cambio,
lee la versión \emph{consignada más reciente} del archivo.

Una consecuencia desafortunada de este diseño es que usted no puede
verificar que su archivo \sfilename{.hgtags} fusionado es correcto hasta
\emph{después} de haber consignado(hecho commit). Así que si se
encuentra resolviendo un conflicto en \sfilename{.hgtags} durante una
fusión, asegúrese de ejecutar la orden \hgcmd{tags} después de
consignar. Si encuentra un error en el archivo \sfilename{.hgtags}, 
reportará el lugar del error, que podrá arreglar y después
consignar. Posteriormente ejecute de nuevo la orden \hgcmd{tags} para
asegurar que su arreglo fue correctamente aplicado.

\subsection{Tags y clonado}

Puede haber notado que la orden \hgcmd{clone} tiene la opción
\hgopt{clone}{-r} que le permite clonar una copia exacta del
repositorio hasta un conjunto de cambios específico. El nuevo clon no
tendrá historia posterior a la revisión que usted haya
especificado. Esta forma de interactuar puede sorprender a los
desprevenidos.

Recuerde que un tag se almacena como una revisión al archivo
\sfilename{.hgtags}, consecuente con esto, cuando crea un tag, el
conjunto de cambios en el cual este se almacena necesariamente se
refiere a un conjunto de cambios anterior. Cuando ejecuta
\hgcmdargs{clone}{-r foo} para clonar un repositorio hasta el tag
\texttt{foo}, el nuevo clon \emph{no contendrá la historia que creo
el tag} que usó para clonar el repositorio. El resultado es que tendrá
exactamente el subconjunto correcto de la historia del proyecto en el
nuevo repositorio, pero, \emph{no} el tag que podría haber esperado.

\subsection{Cuando los tags permanentes son demasiado}

Dado que los tags de Mercurial están controlados por revisiones y se
llevan en la historia del proyecto, todas las personas involucradas
verán los tags que usted haya creado. El hecho de dar nombres a las
revisiones tiene usos más allá que simplemente hacer notar que la
revisión \texttt{4237e45506ee} es realmente \texttt{v2.0.2}.  Si está
tratando de encontrar un bug sutil, posiblemente desearía colocar un
tag recordándole algo como ``Ana vió los síntomas con esta revisión''.

Para estos casos, lo que posiblemente desearía serían tags
\emph{locales}. Puede crear un tag local con la opción \hgopt{tag}{-l}
de la orden \hgcmd{tag}.  Esto guardará el tag en un archivo llamado
\sfilename{.hg/localtags}.  A diferencia de \sfilename{.hgtags},
\sfilename{.hg/localtags} no está controlado por revisiones.
Cualquier tag que usted cree usando \hgopt{tag}{-l} se mantendrá
localmente en el repositorio en el que esté trabajando en ese momento.

\section{El flujo de cambios---El gran cuadro vs. el pequeño}

Retomando lo mencionado en el comienzo de un capítulo, pensemos en el
hecho de que un proyecto tiene muchas piezas concurrentes de trabajo
en desarrollo al mismo tiempo.

Puede haber prisa por una nueva versión ``principal''; Un nueva
versión con un rreglo de fallo a la última versión; y una versión de
``mantenimiento correctivo'' a una versión antigua que ha entrado en
modo de mantenimiento.

Usualmente la gente se refiere a esas direcciones
concurrentes de desarrollo es como ``ramas''.  Aunque hemos visto que
en variadas ocasiones Mercurial trata a \emph{toda la historia} como
una serie de ramas y fusiones.  Realmente lo que tenemos aquí es dos
ideas que se relacionan periféricamente, pero que en esencia comparten
un nombre.
\begin{itemize}
\item ``El gran cuadro'' Las ramas representan un barrido de la
  evolución del proyecto; la gente les da nombres y hablan acerca de
  ellas en sus conversaciones.
\item ``El cuadro pequeño'' Las ramas son artefactos de las
  actividades diarias de al desarrollar y fusionar cambios. Exponen la
  narrativa de cómo se desarrolló el código.
\end{itemize}

\section{Administrar ramas en el gran cuadro en los repositorios}

The easiest way to isolate a ``big picture'' branch in Mercurial is in
a dedicated repositorio.  If you have an existing shared
repositorio---let's call it \texttt{myproject}---that reaches a ``1.0''
milestone, you can start to prepare for future maintenance releases on
top of version~1.0 by tagging the revision from which you prepared
the~1.0 release.
\interaction{branch-repo.tag}
You can then clone a new shared \texttt{myproject-1.0.1} repositorio as
of that tag.
\interaction{branch-repo.clone}

Afterwards, if someone needs to work on a bug fix that ought to go
into an upcoming~1.0.1 minor release, they clone the
\texttt{myproject-1.0.1} repositorio, make their changes, and push them
back.
\interaction{branch-repo.bugfix}
Meanwhile, development for the next major release can continue,
isolated and unabated, in the \texttt{myproject} repositorio.
\interaction{branch-repo.new}

\section{Don't repeat yourself: merging across branches}

In many cases, if you have a bug to fix on a maintenance branch, the
chances are good that the bug exists on your project's main branch
(and possibly other maintenance branches, too).  It's a rare developer
who wants to fix the same bug multiple times, so let's look at a few
ways that Mercurial can help you to manage these bugfixes without
duplicating your work.

In the simplest instance, all you need to do is pull changes from your
maintenance branch into your local clone of the target branch.
\interaction{branch-repo.pull}
You'll then need to merge the heads of the two branches, and push back
to the main branch.
\interaction{branch-repo.merge}

\section{Naming branches within one repositorio}

In most instances, isolating branches in repositorios is the right
approach.  Its simplicity makes it easy to understand; and so it's
hard to make mistakes.  There's a one-to-one relationship between
branches you're working in and directories on your system.  This lets
you use normal (non-Mercurial-aware) tools to work on files within a
branch/repositorio.

If you're more in the ``power user'' category (\emph{and} your
collaborators are too), there is an alternative way of handling
branches that you can consider.  I've already mentioned the
human-level distinction between ``small picture'' and ``big picture''
branches.  While Mercurial works with multiple ``small picture''
branches in a repositorio all the time (for example after you pull
changes in, but before you merge them), it can \emph{also} work with
multiple ``big picture'' branches.

The key to working this way is that Mercurial lets you assign a
persistent \emph{name} to a branch.  There always exists a branch
named \texttt{default}.  Even before you start naming branches
yourself, you can find traces of the \texttt{default} branch if you
look for them.

As an example, when you run the \hgcmd{commit} command, and it pops up
your editor so that you can enter a commit message, look for a line
that contains the text ``\texttt{HG: branch default}'' at the bottom.
This is telling you that your commit will occur on the branch named
\texttt{default}.

To start working with named branches, use the \hgcmd{branches}
command.  This command lists the named branches already present in
your repositorio, telling you which changeset is the tip of each.
\interaction{branch-named.branches}
Since you haven't created any named branches yet, the only one that
exists is \texttt{default}.

To find out what the ``current'' branch is, run the \hgcmd{branch}
command, giving it no arguments.  This tells you what branch the
parent of the current changeset is on.
\interaction{branch-named.branch}

To create a new branch, run the \hgcmd{branch} command again.  This
time, give it one argument: the name of the branch you want to create.
\interaction{branch-named.create}

After you've created a branch, you might wonder what effect the
\hgcmd{branch} command has had.  What do the \hgcmd{status} and
\hgcmd{tip} commands report?
\interaction{branch-named.status}
Nothing has changed in the working directory, and there's been no new
history created.  As this suggests, running the \hgcmd{branch} command
has no permanent effect; it only tells Mercurial what branch name to
use the \emph{next} time you commit a changeset.

When you commit a change, Mercurial records the name of the branch on
which you committed.  Once you've switched from the \texttt{default}
branch to another and committed, you'll see the name of the new branch
show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands
that display the same kind of output.
\interaction{branch-named.commit}
The \hgcmd{log}-like commands will print the branch name of every
changeset that's not on the \texttt{default} branch.  As a result, if
you never use named branches, you'll never see this information.

Once you've named a branch and committed a change with that name,
every subsequent commit that descends from that change will inherit
the same branch name.  You can change the name of a branch at any
time, using the \hgcmd{branch} command.  
\interaction{branch-named.rebranch}
In practice, this is something you won't do very often, as branch
names tend to have fairly long lifetimes.  (This isn't a rule, just an
observation.)

\section{Dealing with multiple named branches in a repositorio}

If you have more than one named branch in a repositorio, Mercurial will
remember the branch that your working directory on when you start a
command like \hgcmd{update} or \hgcmdargs{pull}{-u}.  It will update
the working directory to the tip of this branch, no matter what the
``repo-wide'' tip is.  To update to a revision that's on a different
named branch, you may need to use the \hgopt{update}{-C} option to
\hgcmd{update}.

This behaviour is a little subtle, so let's see it in action.  First,
let's remind ourselves what branch we're currently on, and what
branches are in our repositorio.
\interaction{branch-named.parents}
We're on the \texttt{bar} branch, but there also exists an older
\hgcmd{foo} branch.

We can \hgcmd{update} back and forth between the tips of the
\texttt{foo} and \texttt{bar} branches without needing to use the
\hgopt{update}{-C} option, because this only involves going backwards
and forwards linearly through our change history.
\interaction{branch-named.update-switchy}

If we go back to the \texttt{foo} branch and then run \hgcmd{update},
it will keep us on \texttt{foo}, not move us to the tip of
\texttt{bar}.
\interaction{branch-named.update-nothing}

Committing a new change on the \texttt{foo} branch introduces a new
head.
\interaction{branch-named.foo-commit}

\section{Branch names and merging}

As you've probably noticed, merges in Mercurial are not symmetrical.
Let's say our repositorio has two heads, 17 and 23.  If I
\hgcmd{update} to 17 and then \hgcmd{merge} with 23, Mercurial records
17 as the first parent of the merge, and 23 as the second.  Whereas if
I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23
as the first parent, and 17 as the second.

This affects Mercurial's choice of branch name when you merge.  After
a merge, Mercurial will retain the branch name of the first parent
when you commit the result of the merge.  If your first parent's
branch name is \texttt{foo}, and you merge with \texttt{bar}, the
branch name will still be \texttt{foo} after you merge.

It's not unusual for a repositorio to contain multiple heads, each with
the same branch name.  Let's say I'm working on the \texttt{foo}
branch, and so are you.  We commit different changes; I pull your
changes; I now have two heads, each claiming to be on the \texttt{foo}
branch.  The result of a merge will be a single head on the
\texttt{foo} branch, as you might hope.

But if I'm working on the \texttt{bar} branch, and I merge work from
the \texttt{foo} branch, the result will remain on the \texttt{bar}
branch.
\interaction{branch-named.merge}

To give a more concrete example, if I'm working on the
\texttt{bleeding-edge} branch, and I want to bring in the latest fixes
from the \texttt{stable} branch, Mercurial will choose the ``right''
(\texttt{bleeding-edge}) branch name when I pull and merge from
\texttt{stable}.

\section{Branch naming is generally useful}

You shouldn't think of named branches as applicable only to situations
where you have multiple long-lived branches cohabiting in a single
repositorio.  They're very useful even in the one-branch-per-repositorio
case.  

In the simplest case, giving a name to each branch gives you a
permanent record of which branch a changeset originated on.  This
gives you more context when you're trying to follow the history of a
long-lived branchy project.

If you're working with shared repositorios, you can set up a
\hook{pretxnchangegroup} hook on each that will block incoming changes
that have the ``wrong'' branch name.  This provides a simple, but
effective, defence against people accidentally pushing changes from a
``bleeding edge'' branch to a ``stable'' branch.  Such a hook might
look like this inside the shared repo's \hgrc.
\begin{codesample2}
  [hooks]
  pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch
\end{codesample2}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "00book"
%%% End: