comparison es/collab.tex @ 511:a9ea523446cc

Started translating collab chapter to spanish

508:04ba1c7785ae

\chapter{Collaborating with other people}
\label{cha:collab}

As a completely decentralised tool, Mercurial doesn't impose any
policy on how people ought to work with each other.  However, if
you're new to distributed revision control, it helps to have some
tools and examples in mind when you're thinking about possible
workflow models.

\section{Mercurial's web interface}

Mercurial has a powerful web interface that provides several 
useful capabilities.

For interactive use, the web interface lets you browse a single
repository or a collection of repositories.  You can view the history
of a repository, examine each change (comments and diffs), and view
the contents of each directory and file.

Also for human consumption, the web interface provides an RSS feed of
the changes in a repository.  This lets you ``subscribe'' to a
repository using your favourite feed reader, and be automatically
notified of activity in that repository as soon as it happens.  I find
this capability much more convenient than the model of subscribing to
a mailing list to which notifications are sent, as it requires no
additional configuration on the part of whoever is serving the
repository.

The web interface also lets remote users clone a repository, pull
changes from it, and (when the server is configured to permit it) push
changes back to it.  Mercurial's HTTP tunneling protocol aggressively
compresses data, so that it works efficiently even over low-bandwidth
network connections.

The easiest way to get started with the web interface is to use your
web browser to visit an existing repository, such as the master
Mercurial repository at
\url{http://www.selenic.com/repo/hg?style=gitweb}.

If you're interested in providing a web interface to your own
repositories, Mercurial provides two ways to do this.  The first is
using the \hgcmd{serve} command, which is best suited to short-term
``lightweight'' serving.  See section~\ref{sec:collab:serve} below for
details of how to use this command.  If you have a long-lived
repository that you'd like to make permanently available, Mercurial
has built-in support for the CGI (Common Gateway Interface) standard,
which all common web servers support.  See
section~\ref{sec:collab:cgi} for details of CGI configuration.

\section{Collaboration models}

With a suitably flexible tool, making decisions about workflow is much
more of a social engineering challenge than a technical one.
Mercurial imposes few limitations on how you can structure the flow of
work in a project, so it's up to you and your group to set up and live
with a model that matches your own particular needs.

\subsection{Factors to keep in mind}

The most important aspect of any model that you must keep in mind is
how well it matches the needs and capabilities of the people who will
be using it.  This might seem self-evident; even so, you still can't
afford to forget it for a moment.

I once put together a workflow model that seemed to make perfect sense
to me, but that caused a considerable amount of consternation and
strife within my development team.  In spite of my attempts to explain
why we needed a complex set of branches, and how changes ought to flow
between them, a few team members revolted.  Even though they were
smart people, they didn't want to pay attention to the constraints we
were operating under, or face the consequences of those constraints in
the details of the model that I was advocating.

Don't sweep foreseeable social or technical problems under the rug.
Whatever scheme you put into effect, you should plan for mistakes and
problem scenarios.  Consider adding automated machinery to prevent, or
quickly recover from, trouble that you can anticipate.  As an example,
if you intend to have a branch with not-for-release changes in it,
you'd do well to think early about the possibility that someone might
accidentally merge those changes into a release branch.  You could
avoid this particular problem by writing a hook that prevents changes
from being merged from an inappropriate branch.

\subsection{Informal anarchy}

I wouldn't suggest an ``anything goes'' approach as something
sustainable, but it's a model that's easy to grasp, and it works
perfectly well in a few unusual situations.

As one example, many projects have a loose-knit group of collaborators
who rarely physically meet each other.  Some groups like to overcome
the isolation of working at a distance by organising occasional
``sprints''.  In a sprint, a number of people get together in a single
location (a company's conference room, a hotel meeting room, that kind
of place) and spend several days more or less locked in there, hacking
intensely on a handful of projects.

A sprint is the perfect place to use the \hgcmd{serve} command, since
\hgcmd{serve} does not requires any fancy server infrastructure.  You
can get started with \hgcmd{serve} in moments, by reading
section~\ref{sec:collab:serve} below.  Then simply tell the person
next to you that you're running a server, send the URL to them in an
instant message, and you immediately have a quick-turnaround way to
work together.  They can type your URL into their web browser and
quickly review your changes; or they can pull a bugfix from you and
verify it; or they can clone a branch containing a new feature and try
it out.

The charm, and the problem, with doing things in an ad hoc fashion
like this is that only people who know about your changes, and where
they are, can see them.  Such an informal approach simply doesn't
scale beyond a handful people, because each individual needs to know
about $n$ different repositories to pull from.

\subsection{A single central repository}

For smaller projects migrating from a centralised revision control
tool, perhaps the easiest way to get started is to have changes flow
through a single shared central repository.  This is also the
most common ``building block'' for more ambitious workflow schemes.

Contributors start by cloning a copy of this repository.  They can
pull changes from it whenever they need to, and some (perhaps all)
developers have permission to push a change back when they're ready
for other people to see it.

Under this model, it can still often make sense for people to pull
changes directly from each other, without going through the central
repository.  Consider a case in which I have a tentative bug fix, but
I am worried that if I were to publish it to the central repository,
it might subsequently break everyone else's trees as they pull it.  To
reduce the potential for damage, I can ask you to clone my repository
into a temporary repository of your own and test it.  This lets us put
off publishing the potentially unsafe change until it has had a little
testing.

In this kind of scenario, people usually use the \command{ssh}
protocol to securely push changes to the central repository, as
documented in section~\ref{sec:collab:ssh}.  It's also usual to
publish a read-only copy of the repository over HTTP using CGI, as in
section~\ref{sec:collab:cgi}.  Publishing over HTTP satisfies the
needs of people who don't have push access, and those who want to use
web browsers to browse the repository's history.

\subsection{Working with multiple branches}

Projects of any significant size naturally tend to make progress on
several fronts simultaneously.  In the case of software, it's common
for a project to go through periodic official releases.  A release
might then go into ``maintenance mode'' for a while after its first
publication; maintenance releases tend to contain only bug fixes, not
new features.  In parallel with these maintenance releases, one or
more future releases may be under development.  People normally use
the word ``branch'' to refer to one of these many slightly different
directions in which development is proceeding.

Mercurial is particularly well suited to managing a number of
simultaneous, but not identical, branches.  Each ``development
direction'' can live in its own central repository, and you can merge
changes from one to another as the need arises.  Because repositories
are independent of each other, unstable changes in a development
branch will never affect a stable branch unless someone explicitly
merges those changes in.

Here's an example of how this can work in practice.  Let's say you
have one ``main branch'' on a central server.
\interaction{branching.init}
People clone it, make changes locally, test them, and push them back.

Once the main branch reaches a release milestone, you can use the
\hgcmd{tag} command to give a permanent name to the milestone
revision.
\interaction{branching.tag}
Let's say some ongoing development occurs on the main branch.
\interaction{branching.main}
Using the tag that was recorded at the milestone, people who clone
that repository at any time in the future can use \hgcmd{update} to
get a copy of the working directory exactly as it was when that tagged
revision was committed.  
\interaction{branching.update}

In addition, immediately after the main branch is tagged, someone can
then clone the main branch on the server to a new ``stable'' branch,
also on the server.
\interaction{branching.clone}

Someone who needs to make a change to the stable branch can then clone
\emph{that} repository, make their changes, commit, and push their
changes back there.
\interaction{branching.stable}
Because Mercurial repositories are independent, and Mercurial doesn't
move changes around automatically, the stable and main branches are
\emph{isolated} from each other.  The changes that you made on the
main branch don't ``leak'' to the stable branch, and vice versa.

You'll often want all of your bugfixes on the stable branch to show up
on the main branch, too.  Rather than rewrite a bugfix on the main
branch, you can simply pull and merge changes from the stable to the
main branch, and Mercurial will bring those bugfixes in for you.
\interaction{branching.merge}
The main branch will still contain changes that are not on the stable
branch, but it will also contain all of the bugfixes from the stable
branch.  The stable branch remains unaffected by these changes.

\subsection{Feature branches}

For larger projects, an effective way to manage change is to break up
a team into smaller groups.  Each group has a shared branch of its

511:a9ea523446cc

\chapter{Colaborar con otros}
\label{cha:collab}

Debido a su naturaleza descentralizada, Mercurial no impone política
alguna de cómo deben trabajar los grupos de personas. Sin embargo, si
usted es nuvo al control distribuido de versiones, es bueno tener
herramientas y ejemplos a la mano al pensar en posibles modelos de
flujo de trabajo.

\section{La interfaz web de Mercurial}

Mercurial tiene una poderosa interfaz web que provee bastantes
capacidades útiles.

Para uso interactivo, la interfaz le permite visualizar uno o varios
repositorios. Puede ver la historia de un repositorio, examinar cada
cambio(comentarios y diferencias), y ver los contenidos de cada
directorio y fichero.

Adicionalmente la interfaz provee feeds de RSS de los cambios de los
repositorios. Que le permite ``subscribirse''a un repositorio usando
su herramienta de lectura de feeds favorita, y ser notificado
automáticamente de la actividad en el repositorio tan pronto como
sucede. Me gusta mucho más este modelo que el estar suscrito a una
lista de correo a la cual se envían las notificaciones, dado que no
requiere configuración adicional de parte de quien sea que está
administrando el repositorio.

La interfaz web también permite clonar repositorios a los usuarios
remotos, jalar cambios, y (cuando el servidor está configurado para
permitirlo) publicar cambios en el mismo.  El protocolo de tunneling
de Mercurial comprime datos agresivamente, de forma que trabaja
eficientemente incluso con conexiones de red con poco ancho de banda.

La forma más sencilla de iniciarse con la interfaz web es usar su
navegador para visitar un repositorio existente, como por ejemplo el
repositorio principal de Mercurial \url{http://www.selenic.com/repo/hg?style=gitweb}.

Si está interesado en proveer una interfaz web a sus propios
repositorios, Mercurial provee dos formas de hacerlo.  La primera es
usando la orden \hgcmd{serve}, que está enfocada a servir ``de forma
liviana'' y por intervalos cortos.  Para más detalles de cómo usar
esta orden vea la sección~\ref{sec:collab:serve} más adelante. Si
tiene un repositorio que desea hacer permanente, Mercurial tiene
soporte embebido del \command{ssh} para publicar cambios con seguridad
al repositorio central, como se documenta en la
sección~\ref{sec:collab:ssh}.  Es muy usual que se publique una copia
de sólo lectura en el repositorio que está corriendo sobre HTTP usando
CGI, como en la sección~\ref{sec:collab:cgi}.  Publicar sobre HTTP
satisface las necesidades de la gente que no tiene permisos de
publicación y de aquellos que quieren usar navegadores web para
visualizar la historia del repositorio.

\subsection{Trabajo con muchas ramas}

Los proyectos de cierta talla tienden naturlamente a progresar de
forma simultánea en varios frentes. En el caso del software, es común
que un proyecto tenga versiones periódicas oficiales. Una versión
puede entrar a ``modo mantenimiento'' por un tiempo después de su
primera publicación; las versiones de mantenimiento tienden a contener
solamente arreglos de fallos, pero no nuevas características. En
paralelo con las versiones de mantenimiento puede haber una o muchas
versiones futuras pueden estar en desarrollo. La gente usa normalmente
la palabra ``rama'' para referirse a una de las direcciones
ligeramente distintas en las cuales procede el desarrollo.

Mercurial está especialmente preparado para administrar un buen número
de ramas simultáneas pero no idénticas. Cada ``dirección de
desarrollo'' puede vivir en su propio repositorio central, y puede
mezclar los cambios de una a otra de acuerdo con las necesidades. Dado
que los repositorios son independientes, uno del otro, los cambios
inestables de una rama de desarrollo nunca afectarán una rama estable
a menos que alguien explícitamente mezcle los cambios.

A continuación un ejemplo de cómo podría hacerse esto en la
práctica. Digamos que tiene una ``rama principal'' en un servidor
central.
\interaction{branching.init}
Alguien lo clona, hace cambios locales, los prueba, y los publica allí
mismo.

Una vez que la rama principal alcanza una estado de versión se puede
usar la orden \hgcmd{tag} para dar un nombre permanente a la revisión.
\interaction{branching.tag}
Digamos que en la rama principal ocurre más desarrollo.
\interaction{branching.main}
Cuando se usa la etiqueta con que se identificó la versión, la gente
puede clonar el repositorio en cualquier momento en el futuro
empleando \hgcmd{update} para obtener una copia del directorio de
trabajo exacta como cuando se creó la etiqueta de la revisión que se
consignó.
\interaction{branching.update}

Adicionalmente, justo después de que la rama principal se etiquete,
alguien puede clonarla en el servidor a una nueva rama ``estable'',
también en el servidor.
\interaction{branching.clone}

Alguien que requiera hacer un cambio en la rama estable puede clonar
\emph{ese} repositorio, hacer sus cambios, consignar y publicarlos
posteriormente al inicial.
\interaction{branching.stable}
Puesto que los repositorios de Mercurial son independientes, y que
Mercurial no mueve los cambios de un lado a otro automáticamente, las
ramas estable y principal están \emph{aisladas} la una de la otra.
Los cambios que haga en la rama principal no ``se filtran'' a la rama
estable o vice versa.

Es usual que los arreglos de fallos de la rama estable deban hacerse
aparecer en la rama principal también.  En lugar de reescribir el
arreglo del fallo en la rama principal, puede jalar y mezclar los
cambios de la rama estable a la principal, Mercurial traerá tales
arreglos por usted.
\interaction{branching.merge}
La rama principal contendtrá aún los cambios que no están en la
estable y contendrá además todos los arreglos de fallos de la rama
estable.  La rama estable permanece incólume a tales cambios.

\subsection{Feature branches}

For larger projects, an effective way to manage change is to break up
a team into smaller groups.  Each group has a shared branch of its