view es/collab.tex @ 527:35370f1551a7

finished ssh part translation

\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 nuevo 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{Ramas de Características}

En proyectos grandes, una forma efectiva de administrar los cambios es
dividir el equipo en grupos más pequeños. Cada grupo tiene una rama
compartida, clonada de una rama ``principal'' que conforma el proyecto
completo.   Aquellos que trabajan en ramas individuales típicamente
están aislados de los desarrollos de otras ramas.

\begin{figure}[ht]
  \centering
  \grafix{feature-branches}
  \caption{Ramas de Características}
  \label{fig:collab:feature-branches}
\end{figure}

Cuando una rama particular alcanza un estado deseado, alguien del
equipo de características jala y fusiona de la rama principal hacia
la rama de características y publica posteriormente a la rama principal.

\subsection{El tren de publicación}

Algunos proyectos se organizan al estilo``tren'': Una versión se
planifica para ser liberada cada cierto tiempo, y las características
que estén listas cuando ha llegado el momento ``tren'', se incorporan.

Este modelo tiene cierta similitud a las ramas de características. La
diferencia es que cuando una característica pierde el tren, alguien en
el equipo de características jala y fusiona los cambios que se fueron
en la versión liberada hacia la rama de característica, y el trabajo
continúa sobre lo fusionado para que la característica logre estar en
la próxima versión.

\subsection{El modelo del kernel linux}

El desarrollo del Kernel Linux tiene una estructura jerárquica
bastante horizontal, rodeada de una nube de caos aparente. Dado que la
mayoría de desarrolladores usan \command{git}, una herramienta distribuida
de control de versiones con capacidades similares a Mercurial, resulta
de utilidad describir la forma en que el trabajo fluye en tal
ambiente; si le gustan las ideas, la aproximación se traduce bien
entre Git y Mercurial.

En el centro de la comunidad está Linus Torvalds, el creador de Linux.
Él publica un único repositorio que es considerado el árbol
``oficial'' actual por la comunidad completa de
desarrolladores. Cualquiera puede clonar el árbol de Linus, pero él es
muy selectivo acerca de los árboles de los cuales jala.

Linus tiene varios ``lugartenientes confiables''.  Como regla, él jala
todos los cambios que ellos publican, en la mayoría de los casos sin
siquiera revisarlos.  Algunos de sus lugartenientes generalmente
aceptan ser los ``mantenedores'', responsables de subsistemas
específicos dentro del kernel.  Si un hacker cualquiera desea hacer un
cambio a un subsistema y busca que termine en el árbol de Linus, debe
encontrar quién es el mantenedor del subsistema y solicitarle que
tenga en cuenta su cambio.  Si el mantenedor revisa los cambios y está
de acuerdo en tomarlos, estos pasarán al árbol de Linus de acuerdo a
lo expuesto.

Cada lugarteniente tiene su forma particular de revisar, aceptar y
publicar los cambios; y para decidir cuando hacerlos presentes a
Linus.  Adicionalmente existen varias ramas conocidas que mucha gente
usa para propósitos distintos. Por ejemplo, pocas personas mantienen
repositorios ``estables'' de versiones anteriores del kernel, a los
cuales aplican arreglos de fallos críticos necesarios. Algunos
mantenedores publican varios árboles: uno para cambios
experimentales; uno para cambios que van a ofrecer al mantenedor
principal; y así sucesivamente. Otros publican un solo árbol.

Este modelo tiene dos características notables. La primera es que son
de ``jalar exclusivamente''.  Usted debe solicitar, convencer o
incluso rogar a otro desarrollador para que tome sus cabmios, porque
casi no hay árboles en los cuales más de una persona pueda publicar, y
no hay forma de publicar cambios en un árbol que otra persona controla.

El segundo está basado en reputación y meritocracia.  Si usted es un
desconocido, Linus probablemente ignorará sus cambios, sin siquiera
responderle.  Pero un mantenedor de un subsistema probablemente los
revisara, y los acogerá en caso de que aprueben su criterio de
aplicabilidad.  A medida que usted ofrezca ``mejores'' cambios a un
mantenedor, habrá más posibilidad de que se confíe en su juicio y se
acepten los cambios.   Si usted es reconocido y matiene una rama
durante bastante tiempo para algo que Linus no ha aceptado, personas
con intereses similares pueden jalar sus cambios regularmente para
estar al día con su trabajo.

La reputación y meritocracia no necesariamente es transversal entre
``personas'' de diferentes subsistemas.  Si usted es respetado pero es
un hacker en almacenamiento y trata de arreglar un fallo de redes,
tal cambio puede recibir un nivel de escrutinio de un mantenedor de
redes comparable con el que se le haría a un completo extraño.

Personas que vienen de proyectos con un ordenamiento distinto, sienten
que el proceso comparativamente caótico del Kernel Linux es
completamente lunático.  Es objeto de los caprichos individuales; la
gente desecha cambios cuando lo desean; y la fase de desarrollo es
alucinante. A pesar de eso Linux es una pieza de software exitosa y
bien reconocida.

\subsection{Solamente jalar frente a colaboración pública}

Una fuente perpetua de discusiones en la comunidad de código abierto
yace en el modelo de desarrollo en el cual la gente solamente jala
cambios de otros ``es mejor que'' uno  en el cual muchas personas
pueden publicar cambios a un repositorio compartido.

Tícamente los partidarios del modelo de publicar usan las herramientas
que se apegan a este modelo.  Si usted usa una herramienta
centralizada de control de versiones como Subversion, no hay forma de
elegir qué modelo va a usar: La herramienta le ofrece publicación
compartida, y si desea hacer cualquier otra cosa, va a tener que
aplicar una aproximación artificial (tal como aplicar parches a mano).

Una buena herramienta distribuida de control de versiones, tal como
Mercurial soportará los dos modelos.   Usted y sus colaboradores
pueden estructurar cómo trabajarán juntos basados en sus propias
necesidades y preferencias,  sin depender de las peripecias que la
herramienta les obligue a hacer.

\subsection{Cuando la colaboración encuentra la administración ramificada}

Una vez que usted y su equipo configurar algunos repositorios
compartidos y comienzan a propagar cambios entre sus repositorios
locales y compartidos, comenzará a encarar un reto relacionado, pero
un poco distinto:  Administrar las direcciones en las cuales su equipo
puede moverse.   A pesar de que está intimamente ligado acerca de cómo
interactúa su equipo, es lo suficientemente denso para ameritar un
tratamiento en el capítulo~\ref{chap:branch}.

\section{Aspectos técnicos de la colaboración}

Lo que resta del capítulo lo dedicamos a las cuestiones de servir
datos a sus colaboradores.

\section{Compartir informalmente con \hgcmd{serve}}
\label{sec:collab:serve}

La orden \hgcmd{serve} de Mercurial satisface de forma espectacular
las necesidades de un grupo pequeño, acoplado y de corto
tiempo.  Se constituye en una demostración de cómo se siente usar los
comandos usando la red.

Ejecute \hgcmd{serve} dentro de un repositorio, y en pocos segundos
iniciará un servidor HTTP especializado; aceptará conexiones desde
cualquier cliente y servirá datos de este repositorio mientrs lo
mantenga funcionando. Todo el que sepa el URL del servidor que ha
iniciado, y que puede comunicarse con su computador por la red, puede
usar un navegador web o Mercurial para leer datos del repositorio. Un
URL para una instancia de \hgcmd{serve} ejecutándose en un portátil
debería lucir algo \Verb|http://my-laptop.local:8000/|.

La orden \hgcmd{serve} \emph{no} es un servidor web de propósito
general. Solamente puede hacer dos cosas:
\begin{itemize}
\item Permitir que se pueda visualizar la historia del repositorio que
  está sirviendo desde navegadores web.
\item Hablar el protocolo de conexión de Mercurial para que puedan hacer
  \hgcmd{clone} o \hgcmd{pull} (jalar) cambios de tal repositorio.
\end{itemize}
En particular, \hgcmd{serve} no permitirá que los usuarios remotos
puedan \emph{modificar} su repositorio.  Es de tipo solo lectura.

Si está comenzando con Mercurial, no hay nada que le impida usar
\hgcmd{serve} para servir un repositorio en su propio computador, y
usar posteriormente órdenes como \hgcmd{clone}, \hgcmd{incoming}, para
comunicarse con el servidor como si el repositorio estuviera alojado
remotamente. Lo que además puede ayudarle a adecuarse rápidamente para
usar comandos en repositorios alojados en la red.

\subsection{Cuestiones adicionales para tener en cuenta}

Dado que permite lectura sin autenticación a todos sus clientes,
debería usar \hgcmd{serve} exclusivamente en ambientes en los cuáles
no tenga problema en que otros vean, o en los cuales tenga control
completo acerca de quien puede acceder a su red y jalar cambios de su
repositorio.

La orden \hgcmd{serve} no tiene conocimiento acerca de programas
cortafuegos que puedan estar instalados en su sistema o en su red. No
puede detectar o controlar sus cortafuegos.  Si otras personas no
pueden acceder a su instancia \hgcmd{serve}, lo siguiente que debería hacer
(\emph{después} de asegurarse que tienen el URL correcto) es verificar
su configuración de cortafuegos.

De forma predeterminada, \hgcmd{serve} escucha conexiones entrantes en
el puerto~8000.  Si otro proceso está escuchando en tal puerto, usted
podrá especificar un puerto distinto para escuchar con la opción
\hgopt{serve}{-p} .

Normalmente, cuando se inicia \hgcmd{serve}, no imprime nada, lo cual
puede ser desconcertante.  Si desea confirmar que en efecto está
ejecutándose correctamente, y darse cuenta qué URL debería enviar a
sus colaboradores, inícielo con la opción \hggopt{-v}.

\section{Uso del protocolo Secure Shell (ssh)}
\label{sec:collab:ssh}

Usted puede publicar y jalar cambios en la red de forma segura usando
el protocolo Secure Shell (\texttt{ssh}).  Para usarlo satisfactoriamente,
tendrá que hacer algo de configuración a nivel de cliente o el
servidor.

Si no está familizarizado con ssh, es un protocolo de red que le permite
comunicarse con seguridad con otro computador.  Para usarlo con
Mercurial, estará estableciendo una o más cuentas de usuario en un
servidor de forma tal que los usuarios remotos puedan entrar y
ejecutar órdenes.

(Si ssh le \emph{es} familiar, encontrará probablemente elemental una
porción del material a continuación.)

\subsection{Cómo leer y escribir URLs de ssh}

Los URLs de ssh tienden a lucir de la siguiente forma:
\begin{codesample2}
  ssh://[e-mail]:22/hg/hgbook
\end{codesample2}
\begin{enumerate}
\item La parte ``\texttt{ssh://}'' indica a Mercurial que use el
  protocolo ssh.
\item El componente ``\texttt{bos@}'' indica el nombre del usuario que
  está entrando al servidor.  Puede omitirl si el usuario remoto
  coincide con el usuario local.
\item ``\texttt{hg.serpentine.com}'' es el nombre del servidor al cual
  se desea entrar.
\item El ``:22'' identifica el número del puerto en el servidor al cual
  se conectará.  El predeterminado es el~22, así que solamente
  necesitará especificar esa porción si \emph{no} está usando el
  puerto~22.
\item La última porción del URL es la ruta local al repositorio en el
  servidor.
\end{enumerate}

El componente de la ruta del URL para ssh es una fuente de confusión,
puesto que no hay una forma estándar para que las herramientas puedan
interpretarlo.  Algunos programas se comportan de manera distinta a
otros cuando manipulan estas rutas.  No es la situación ideal, pero
es muy poco probable que vaya a cambiar.  Por favor lea los párrafos
siguientes cuidadosamente.

Mercurial trata la ruta al repositorio en el servidor como relativo al
directorio chasa del usuario remoto.  Por ejemplo, si el usuario
\texttt{foo} en el servidor tiene el directorio casa
\dirname{/home/foo},
entonces un URL ssh que contenga en su ruta a \dirname{bar}
\emph{realmente} se refiere al directorio \dirname{/home/foo/bar}.

Si desea especificar una ruta relativa a otro directorio de usuario,
puede usar una ruta que comience con un caracter tildado, seguido del
nombre del usuario(llamémosle \texttt{otrousuario}, así
\begin{codesample2}
  ssh://server/~otrousuario/hg/repo
\end{codesample2}

Y si realmente desea especifica una ruta \emph{absoluta} en el
servidor, comience con el componente de la ruta con dos barras como
en el siguiente ejemplo:
\begin{codesample2}
  ssh://server//absolute/path
\end{codesample2}

\subsection{Encontrar un cliente ssh para su sistema}

Casi todos los sistemas tipo Unix vienen con OpenSSH preinstalado.  Si
usted está usando un sistema de estos, ejecute \Verb|which ssh| para
identificar dónde está instalada la orden \command{ssh} (usualmente
estará en \dirname{/usr/bin}).  Si por casualidad no está presente,
vea la documentación de sus sistema para lograr instalarlo.

En Windows, tendrá que escoger primero un cliente adecuado para
descargarlo.  Hay dos alternativas:
\begin{itemize}
\item El excelente paquete PuTTY~\cite{web:putty} de Simon Tatham, que
  ofrece un suite completo de órdenes de cliente ssh.
\item Si tiene alta tolerancia al dolor, puede usar el porte de Cygwin
  para OpenSSH.
\end{itemize}
En cualquier caso, tendrá que editar su fichero \hgini\ para indicarle
a Mercurial dónde encontrar la orden real del cliente.  Por ejemplo, si
está usando PuTTY, tendrá que usar la orden \command{plink} como un
cliente de línea de órdenes.
\begin{codesample2}
  [ui]
  ssh = C:/ruta/a/plink.exe -ssh -i "C:/ruta/a/mi/llave/privada"
\end{codesample2}

\begin{note}
  La ruta a \command{plink} no debería contener espacios o caracteres
  en blanco, o Mercurial no podrá encontrarlo correctamente (por lo
  tanto, probablemente no sería buena idea colocarlo en 
  \dirname{C:\\Program Files}
\end{note}

\subsection{Generar un par de llaves}

Para evitar la necesidad de teclera una clave de forma repetitiva cada
vez que necesita usar el cliente, recomiendo generar un par de llaves.
En un sistema tipo Unix, la orden \command{ssh-keygen} también se
comportará bien. En Windows, si está usando PuTTY, la orden
\command{puttygen} es la que necesitará.

Cuando genera un par de llaves, se aconseja \emph{comedidamente} 
protegerlas con una frase de clave.  (La única oportunidad en la cual
usted querría identificarse una única vez, es cuando está usando
el protocolo ssh para tareas automatizadas en una red segura.)

No basta con generar un par de llaves.  Se requiere adicionar una llave
pública al conjunto de llaves autorizadas para todos los usuarios
remotos que se vayan a autenticar.  Para aquellos servidores que usen
OpenSSH(la gran mayoría), significará añadir la llave pública a la
lista en el fichero llamado \sfilename{authorized\_keys} en su
directorio \sdirname{.ssh}.

En sistemas tipo Unix, su llave pública tendrá la extensión
\filename{.pub}.  Si usa \command{puttygen} en Windows, puede
guardar la llave pública en un fichero de su elección, o pegarla desde
la ventana en la cual se despliega directamente en el fichero
\sfilename{authorized\_keys}.

\subsection{Uso de un agente de autenticación}

Un agente de autentitcación es un daemonio que almacena frases clave en
memoria(olvidará las frases clave si sale y vuelve a entrar).  Un cliente
ssh notará si está corriendo, y solicitará una frase clave.  Si no hay
un agente de autenticación corriendo, o el agente no almacena la frase
clave necesaria, tendrá que teclear su frase clave cada vez que 
Mercurial intente comunicarse con un servidor para usted(p.e.~cada vez
que jale o publique cambios).

El problema de almacenar frases claves en un agente es que es posible
para un atacante bien preparado recuperar el texto plano de su frase
clave, en alguntos casos incluso si su sistema sea muy alternante.
Es su decisión si es un riesgo aceptable.  Lo que si es seguro es que
evita reteclear.

En sistemas tipo Unix, el agente se llama \command{ssh-agent}, y
usualmente se ejecuta automáticamente cuando usted entra.  Tendrá que
usar la orden \command{ssh-add} para añadir frases claves al agente.  En
Windows, si está usando PuTTY, la orden \command{pageant} actúa como
el agente.  Añade un ícono a su barra del sistema que le permitirá
almacenar frases clave.

\subsection{Configurar el lado del servidor apropiadamente}

Dado que puede ser dispendioso configurar ssh si usted es nuevo, hay 
una variedad de cosas que podrían ir mal.  Añada piense primero en
Mercurial y hay mucho más en qué pensar.  La mayor parte de estos
problemas potenciales occuren en el lado del servidor, no en el cliente.
Las buenas noticias es que una vez tiene una configuración funcional,
usualmente continuará trabajando indefinidamente.

Antes de intentar que Mercurial hable con un servidor ssh, es mejor
asegurarse que puede usar la orden normal \command{ssh} o \command{putty}
para comunicarse con el servidor primero.  Si tiene problemas usando
estas órdenes directamente, de seguro Mercurial no funcionará.  Pero aún,
esconderá el problema subyacente.  Cuando desee revisar un problema
relacionado con ssh y Mercurial, debería asegurarse primero que las
órdenes de ssh en el lado del cliente funcionan primero, \emph{antes}
de preocuparse por si existe un problema con Mercurial.

Lo primero para asegurar en el lado del servidor es que puede entrar
desde otra máquina.  Si no puede entrar con \command{ssh} o 
\command{putty}, el mensaje de error que obtenga le puede dar pistas
de qué ha ido mal.  Los problemas más comunes son los siguientes:
\begin{itemize}
\item Si obitene un error de ``conexión rehusada'', es posible que no 
  haya un daemonio SSH corriendo en el servidor o que no pueda accederse
  a él por configuraciones de cortafuegos.
\item Si obtiene un error de ``no hay ruta hasta el servidor'', puede
  tener la dirección del servidor incorrecta o un cortafuegos con
  bloqueo agresivo que no permitirá su existencia.
\item Si obtiene un mensaje de ``permiso denegado'', puede que haya
  tecleado mal el usuario en el servidor, o que haya tecleado
  incorrectamente la frase clave o la clave del usuario remoto.
\end{itemize}
En resumen, si tiene problemas al comunicarse con el daemonio ssh del
servidor, primero asegúrese de que está corriendo.  En muchos sistemas
estará instalado, pero deshabilitado de forma predeterminada.  Una vez
que haya hecho este paso tendrá que revisar si el cortafuegos del
servidor está configurado para recibir conexiones entrantes en el
puerto en el cual el daemonio de ssh está escuchando(usualmente el~22).
No trate de buscar otras posibilidades exóticas o configuraciones
erradas haste que haya revisado primero estas dos.

Si está usando un agente de autenticación en el lado del cliente para
almacenar las frase claves de sus contraseñas, debería poder entrar al
servidor sin necesidad de que se le solicite frases claves o
contraseñas.  Si se le pregunta alguna, a continuación algunas
posibilidades:
\begin{itemize}
\item Puede haber olvidado usar \command{ssh-add} o
  \command{pageant} para guardar la frase clave.
\item Puede haber almacenado una frase clave errónea para la llave.
\end{itemize}
Si se le solicita la clave del usuario remoto, hay otras posibilidades
que deben revisarse:
\begin{itemize}
\item O bien el directorio del usuario o su directorio \sdirname{.ssh}
  tiene permisos excesivamente abiertos.  Como resultado el daemonio
  ssh no creerá o leerá su fichero \sfilename{authorized\_keys}.  
  Por ejemplo, un directorio casa o \sdirname{.ssh} causará aveces
  este síntoma.
\item El fichero de usuario \sfilename{authorized\_keys} puede tener
  un problema.  Si alguien distinto al usuario es dueño o puede
  escribir el archivo, el daemonio ssh no confiará o lo leerá.
\end{itemize}

En un mundo ideal, debería poder ejecutar la siguiente orden
exitósamente, y debería imprimir exactamente una línea de salida,
la fecha y hora actual.
\begin{codesample2}
  ssh miservidor fecha
\end{codesample2}

Si en su servidor tiene guión que se ejecuta a la entrada e imprimie
letreros o cualquier otra cosa, incluso cuando se ejecutan órdenes no
interactivas como esta, debería arreglarlo antes de continuar, de
forma que solamente imprima algo si se ejecuta interactivamente.  De
otra forma estos letreros al menos llenarán la salida de Mercurial.
incluso podrían causar problemas potenciales cuando se ejecuten
órdenes de forma remota.  Mercurial intenta detectar e ignorar los
letreros en sesiones no interactivas de \command{ssh}, pero no es
a prueba de tontos.  (Si edita sus guiones de entrada en el servidor,
la forma usual de ver si un guión de script se ejecuta en un shell
interactivo, es verificar el código de retorno de la orden
\Verb|tty -s|.)

Cuando verifique que el venerado ssh funciona en su servidor, el
paso siguiente es asegurar que Mercurial corre en el servidor.  La
orden siguiente debería ejecutarse satisfactoriamente:
\begin{codesample2}
  ssh miservidor hg version
\end{codesample2}
Si ve un mensaje de error en lugar de la salida usual de 
\hgcmd{version}, será porque no ha instalado Mercurial en
\dirname{/usr/bin}.  No se preocupe si este es el caso; no necesita
hacerlo.  Pero debería revisar los posibles problemas presentados a
continuación:
\begin{itemize}
\item Está instalado Mercurial en el servidor?  Se que suena trivial
  pero es mejor revisar!
\item Tal vez la ruta de búsqueda de la interfaz de órdenes
  (normalmente vía la variable de ambiente \envar{PATH}) simplemente
  está mal configurada.
\item Puede ser que su variable de ambiente \envar{PATH} soalamente
  apunte al lugar en el cual está el ejecutable \command{hg} si la
  sesión de entrada es interactiva.  Puede suceder si establece la
  ruta en el guión de shell de entrada incorrecto.  Consulte la
  documentación de su línea de órdenes.
\item La variable de ambiente \envar{PYTHONPATH} puede requerir la
  ruta a los módulos de Mercurial en Python.  Puede que nisiquiera
  está establecida; podría estar incorrecta; o puede ser que se
  establezca únicamente cuando hay entradas interactivas.
\end{itemize}

Si puede ejecutar \hgcmd{version} sobre una conexión ssh,
felicitaciones!  Ha logrado la interacción entre el cliente y el 
servidor.  Ahora debería poder acceder a los repositorios de
Mercurial que tiene el usuario en el servidor.  Si tiene problemas
con Mercurial y ssh en este punto, intente usar la opción
\hggopt{--debug} para tener información más clara de lo que está
sucediendo.

\subsection{Compresión con ssh}

Mercurial no comprime datos cuando usa el protocolo ssh, dado que
el protocolo puede comprimir datos transparentemente.  Pero el
comportamiento predeterminado del cliente ssh es \emph{no}
solicitar compresión.

Sobre cualquier red distinta a una LAN rápida(incluso con una red
inalámbrica), hacer uso de compresión puede mejorar el rendimiento
de las operaciones de Mercurial que involucren la red.  Por ejemplo,
sobre WAN, alguien ha medido la compresión reduciendo la cantidad
de tiempo requerido para clonar un repositorio particularmente
grande de~51 minutos a~17 minutos.

Tanto \command{ssh} como \command{plink} aceptan la opción
\cmdopt{ssh}{-C} que activa la compresión.  Puede editar fácilmente
su \hgrc\ para habilitar la compresión para todos los usos de
Mercurial sobre el protocolo ssh.
\begin{codesample2}
  [ui]
  ssh = ssh -C
\end{codesample2}

Si usa \command{ssh}, puede reconfigurarlo para que siempre use
compresión cuando se comunique con su servidor.  Para hacerlo,
edite su fichero \sfilename{.ssh/config}(que puede no existir
aún), de la siguiente forma:
\begin{codesample2}
  Host hg
    Compression yes
    HostName hg.ejemplo.com
\end{codesample2}
Que define un alias, \texttt{hg}.  Cuando lo usa con la orden
\command{ssh} o con una URL de Mercurial con protocolo\texttt{ssh},
logrará que \command{ssh} se conecte a \texttt{hg.ejemplo.com}
con compresión.  Que le dará un nombre más corto para teclear y
compresión, los cuales por derecho propio son buenos.

\section{Serving over HTTP using CGI}
\label{sec:collab:cgi}

Depending on how ambitious you are, configuring Mercurial's CGI
interface can take anything from a few moments to several hours.

We'll begin with the simplest of examples, and work our way towards a
more complex configuration.  Even for the most basic case, you're
almost certainly going to need to read and modify your web server's
configuration.

\begin{note}
  Configuring a web server is a complex, fiddly, and highly
  system-dependent activity.  I can't possibly give you instructions
  that will cover anything like all of the cases you will encounter.
  Please use your discretion and judgment in following the sections
  below.  Be prepared to make plenty of mistakes, and to spend a lot
  of time reading your server's error logs.
\end{note}

\subsection{Web server configuration checklist}

Before you continue, do take a few moments to check a few aspects of
your system's setup.

\begin{enumerate}
\item Do you have a web server installed at all?  Mac OS X ships with
  Apache, but many other systems may not have a web server installed.
\item If you have a web server installed, is it actually running?  On
  most systems, even if one is present, it will be disabled by
  default.
\item Is your server configured to allow you to run CGI programs in
  the directory where you plan to do so?  Most servers default to
  explicitly disabling the ability to run CGI programs.
\end{enumerate}

If you don't have a web server installed, and don't have substantial
experience configuring Apache, you should consider using the
\texttt{lighttpd} web server instead of Apache.  Apache has a
well-deserved reputation for baroque and confusing configuration.
While \texttt{lighttpd} is less capable in some ways than Apache, most
of these capabilities are not relevant to serving Mercurial
repositories.  And \texttt{lighttpd} is undeniably \emph{much} easier
to get started with than Apache.

\subsection{Basic CGI configuration}

On Unix-like systems, it's common for users to have a subdirectory
named something like \dirname{public\_html} in their home directory,
from which they can serve up web pages.  A file named \filename{foo}
in this directory will be accessible at a URL of the form
\texttt{http://www.example.com/\~username/foo}.

To get started, find the \sfilename{hgweb.cgi} script that should be
present in your Mercurial installation.  If you can't quickly find a
local copy on your system, simply download one from the master
Mercurial repository at
\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.

You'll need to copy this script into your \dirname{public\_html}
directory, and ensure that it's executable.
\begin{codesample2}
  cp .../hgweb.cgi ~/public_html
  chmod 755 ~/public_html/hgweb.cgi
\end{codesample2}
The \texttt{755} argument to \command{chmod} is a little more general
than just making the script executable: it ensures that the script is
executable by anyone, and that ``group'' and ``other'' write
permissions are \emph{not} set.  If you were to leave those write
permissions enabled, Apache's \texttt{suexec} subsystem would likely
refuse to execute the script.  In fact, \texttt{suexec} also insists
that the \emph{directory} in which the script resides must not be
writable by others.
\begin{codesample2}
  chmod 755 ~/public_html
\end{codesample2}

\subsubsection{What could \emph{possibly} go wrong?}
\label{sec:collab:wtf}

Once you've copied the CGI script into place, go into a web browser,
and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
\emph{but} brace yourself for instant failure.  There's a high
probability that trying to visit this URL will fail, and there are
many possible reasons for this.  In fact, you're likely to stumble
over almost every one of the possible errors below, so please read
carefully.  The following are all of the problems I ran into on a
system running Fedora~7, with a fresh installation of Apache, and a
user account that I created specially to perform this exercise.

Your web server may have per-user directories disabled.  If you're
using Apache, search your config file for a \texttt{UserDir}
directive.  If there's none present, per-user directories will be
disabled.  If one exists, but its value is \texttt{disabled}, then
per-user directories will be disabled.  Otherwise, the string after
\texttt{UserDir} gives the name of the subdirectory that Apache will
look in under your home directory, for example \dirname{public\_html}.

Your file access permissions may be too restrictive.  The web server
must be able to traverse your home directory and directories under
your \dirname{public\_html} directory, and read files under the latter
too.  Here's a quick recipe to help you to make your permissions more
appropriate.
\begin{codesample2}
  chmod 755 ~
  find ~/public_html -type d -print0 | xargs -0r chmod 755
  find ~/public_html -type f -print0 | xargs -0r chmod 644
\end{codesample2}

The other possibility with permissions is that you might get a
completely empty window when you try to load the script.  In this
case, it's likely that your access permissions are \emph{too
  permissive}.  Apache's \texttt{suexec} subsystem won't execute a
script that's group-~or world-writable, for example.

Your web server may be configured to disallow execution of CGI
programs in your per-user web directory.  Here's Apache's
default per-user configuration from my Fedora system.
\begin{codesample2}
  <Directory /home/*/public_html>
      AllowOverride FileInfo AuthConfig Limit
      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
      <Limit GET POST OPTIONS>
          Order allow,deny
          Allow from all
      </Limit>
      <LimitExcept GET POST OPTIONS>
          Order deny,allow
          Deny from all
      </LimitExcept>
  </Directory>
\end{codesample2}
If you find a similar-looking \texttt{Directory} group in your Apache
configuration, the directive to look at inside it is \texttt{Options}.
Add \texttt{ExecCGI} to the end of this list if it's missing, and
restart the web server.

If you find that Apache serves you the text of the CGI script instead
of executing it, you may need to either uncomment (if already present)
or add a directive like this.
\begin{codesample2}
  AddHandler cgi-script .cgi
\end{codesample2}

The next possibility is that you might be served with a colourful
Python backtrace claiming that it can't import a
\texttt{mercurial}-related module.  This is actually progress!  The
server is now capable of executing your CGI script.  This error is
only likely to occur if you're running a private installation of
Mercurial, instead of a system-wide version.  Remember that the web
server runs the CGI program without any of the environment variables
that you take for granted in an interactive session.  If this error
happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
directions inside it to correctly set your \envar{PYTHONPATH}
environment variable.

Finally, you are \emph{certain} to by served with another colourful
Python backtrace: this one will complain that it can't find
\dirname{/path/to/repository}.  Edit your \sfilename{hgweb.cgi} script
and replace the \dirname{/path/to/repository} string with the complete
path to the repository you want to serve up.

At this point, when you try to reload the page, you should be
presented with a nice HTML view of your repository's history.  Whew!

\subsubsection{Configuring lighttpd}

To be exhaustive in my experiments, I tried configuring the
increasingly popular \texttt{lighttpd} web server to serve the same
repository as I described with Apache above.  I had already overcome
all of the problems I outlined with Apache, many of which are not
server-specific.  As a result, I was fairly sure that my file and
directory permissions were good, and that my \sfilename{hgweb.cgi}
script was properly edited.

Once I had Apache running, getting \texttt{lighttpd} to serve the
repository was a snap (in other words, even if you're trying to use
\texttt{lighttpd}, you should read the Apache section).  I first had
to edit the \texttt{mod\_access} section of its config file to enable
\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
disabled by default on my system.  I then added a few lines to the end
of the config file, to configure these modules.
\begin{codesample2}
  userdir.path = "public_html"
  cgi.assign = ( ".cgi" => "" )
\end{codesample2}
With this done, \texttt{lighttpd} ran immediately for me.  If I had
configured \texttt{lighttpd} before Apache, I'd almost certainly have
run into many of the same system-level configuration problems as I did
with Apache.  However, I found \texttt{lighttpd} to be noticeably
easier to configure than Apache, even though I've used Apache for over
a decade, and this was my first exposure to \texttt{lighttpd}.

\subsection{Sharing multiple repositories with one CGI script}

The \sfilename{hgweb.cgi} script only lets you publish a single
repository, which is an annoying restriction.  If you want to publish
more than one without wracking yourself with multiple copies of the
same script, each with different names, a better choice is to use the
\sfilename{hgwebdir.cgi} script.

The procedure to configure \sfilename{hgwebdir.cgi} is only a little
more involved than for \sfilename{hgweb.cgi}.  First, you must obtain
a copy of the script.  If you don't have one handy, you can download a
copy from the master Mercurial repository at
\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.

You'll need to copy this script into your \dirname{public\_html}
directory, and ensure that it's executable.
\begin{codesample2}
  cp .../hgwebdir.cgi ~/public_html
  chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
\end{codesample2}
With basic configuration out of the way, try to visit
\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser.  It
should display an empty list of repositories.  If you get a blank
window or error message, try walking through the list of potential
problems in section~\ref{sec:collab:wtf}.

The \sfilename{hgwebdir.cgi} script relies on an external
configuration file.  By default, it searches for a file named
\sfilename{hgweb.config} in the same directory as itself.  You'll need
to create this file, and make it world-readable.  The format of the
file is similar to a Windows ``ini'' file, as understood by Python's
\texttt{ConfigParser}~\cite{web:configparser} module.

The easiest way to configure \sfilename{hgwebdir.cgi} is with a
section named \texttt{collections}.  This will automatically publish
\emph{every} repository under the directories you name.  The section
should look like this:
\begin{codesample2}
  [collections]
  /my/root = /my/root
\end{codesample2}
Mercurial interprets this by looking at the directory name on the
\emph{right} hand side of the ``\texttt{=}'' sign; finding
repositories in that directory hierarchy; and using the text on the
\emph{left} to strip off matching text from the names it will actually
list in the web interface.  The remaining component of a path after
this stripping has occurred is called a ``virtual path''.

Given the example above, if we have a repository whose local path is
\dirname{/my/root/this/repo}, the CGI script will strip the leading
\dirname{/my/root} from the name, and publish the repository with a
virtual path of \dirname{this/repo}.  If the base URL for our CGI
script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
URL for that repository will be
\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.

If we replace \dirname{/my/root} on the left hand side of this example
with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
\dirname{/my} from the repository name, and will give us a virtual
path of \dirname{root/this/repo} instead of \dirname{this/repo}.

The \sfilename{hgwebdir.cgi} script will recursively search each
directory listed in the \texttt{collections} section of its
configuration file, but it will \texttt{not} recurse into the
repositories it finds.

The \texttt{collections} mechanism makes it easy to publish many
repositories in a ``fire and forget'' manner.  You only need to set up
the CGI script and configuration file one time.  Afterwards, you can
publish or unpublish a repository at any time by simply moving it
into, or out of, the directory hierarchy in which you've configured
\sfilename{hgwebdir.cgi} to look.

\subsubsection{Explicitly specifying which repositories to publish}

In addition to the \texttt{collections} mechanism, the
\sfilename{hgwebdir.cgi} script allows you to publish a specific list
of repositories.  To do so, create a \texttt{paths} section, with
contents of the following form.
\begin{codesample2}
  [paths]
  repo1 = /my/path/to/some/repo
  repo2 = /some/path/to/another
\end{codesample2}
In this case, the virtual path (the component that will appear in a
URL) is on the left hand side of each definition, while the path to
the repository is on the right.  Notice that there does not need to be
any relationship between the virtual path you choose and the location
of a repository in your filesystem.

If you wish, you can use both the \texttt{collections} and
\texttt{paths} mechanisms simultaneously in a single configuration
file.

\begin{note}
  If multiple repositories have the same virtual path,
  \sfilename{hgwebdir.cgi} will not report an error.  Instead, it will
  behave unpredictably.
\end{note}

\subsection{Downloading source archives}

Mercurial's web interface lets users download an archive of any
revision.  This archive will contain a snapshot of the working
directory as of that revision, but it will not contain a copy of the
repository data.

By default, this feature is not enabled.  To enable it, you'll need to
add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
section of your \hgrc.

\subsection{Web configuration options}

Mercurial's web interfaces (the \hgcmd{serve} command, and the
\sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
number of configuration options that you can set.  These belong in a
section named \rcsection{web}.
\begin{itemize}
\item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
  download mechanisms Mercurial supports.  If you enable this
  feature, users of the web interface will be able to download an
  archive of whatever revision of a repository they are viewing.
  To enable the archive feature, this item must take the form of a
  sequence of words drawn from the list below.
  \begin{itemize}
  \item[\texttt{bz2}] A \command{tar} archive, compressed using
    \texttt{bzip2} compression.  This has the best compression ratio,
    but uses the most CPU time on the server.
  \item[\texttt{gz}] A \command{tar} archive, compressed using
    \texttt{gzip} compression.
  \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
    compression.  This format has the worst compression ratio, but is
    widely used in the Windows world.
  \end{itemize}
  If you provide an empty list, or don't have an
  \rcitem{web}{allow\_archive} entry at all, this feature will be
  disabled.  Here is an example of how to enable all three supported
  formats.
  \begin{codesample4}
    [web]
    allow_archive = bz2 gz zip
  \end{codesample4}
\item[\rcitem{web}{allowpull}] Boolean.  Determines whether the web
  interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
  repository over~HTTP.  If set to \texttt{no} or \texttt{false}, only
  the ``human-oriented'' portion of the web interface is available.
\item[\rcitem{web}{contact}] String.  A free-form (but preferably
  brief) string identifying the person or group in charge of the
  repository.  This often contains the name and email address of a
  person or mailing list.  It often makes sense to place this entry in
  a repository's own \sfilename{.hg/hgrc} file, but it can make sense
  to use in a global \hgrc\ if every repository has a single
  maintainer.
\item[\rcitem{web}{maxchanges}] Integer.  The default maximum number
  of changesets to display in a single page of output.
\item[\rcitem{web}{maxfiles}] Integer.  The default maximum number
  of modified files to display in a single page of output.
\item[\rcitem{web}{stripes}] Integer.  If the web interface displays
  alternating ``stripes'' to make it easier to visually align rows
  when you are looking at a table, this number controls the number of
  rows in each stripe.
\item[\rcitem{web}{style}] Controls the template Mercurial uses to
  display the web interface.  Mercurial ships with two web templates,
  named \texttt{default} and \texttt{gitweb} (the latter is much more
  visually attractive).  You can also specify a custom template of
  your own; see chapter~\ref{chap:template} for details.  Here, you
  can see how to enable the \texttt{gitweb} style.
  \begin{codesample4}
    [web]
    style = gitweb
  \end{codesample4}
\item[\rcitem{web}{templates}] Path.  The directory in which to search
  for template files.  By default, Mercurial searches in the directory
  in which it was installed.
\end{itemize}
If you are using \sfilename{hgwebdir.cgi}, you can place a few
configuration items in a \rcsection{web} section of the
\sfilename{hgweb.config} file instead of a \hgrc\ file, for
convenience.  These items are \rcitem{web}{motd} and
\rcitem{web}{style}.

\subsubsection{Options specific to an individual repository}

A few \rcsection{web} configuration items ought to be placed in a
repository's local \sfilename{.hg/hgrc}, rather than a user's or
global \hgrc.
\begin{itemize}
\item[\rcitem{web}{description}] String.  A free-form (but preferably
  brief) string that describes the contents or purpose of the
  repository.
\item[\rcitem{web}{name}] String.  The name to use for the repository
  in the web interface.  This overrides the default name, which is the
  last component of the repository's path.
\end{itemize}

\subsubsection{Options specific to the \hgcmd{serve} command}

Some of the items in the \rcsection{web} section of a \hgrc\ file are
only for use with the \hgcmd{serve} command.
\begin{itemize}
\item[\rcitem{web}{accesslog}] Path.  The name of a file into which to
  write an access log.  By default, the \hgcmd{serve} command writes
  this information to standard output, not to a file.  Log entries are
  written in the standard ``combined'' file format used by almost all
  web servers.
\item[\rcitem{web}{address}] String.  The local address on which the
  server should listen for incoming connections.  By default, the
  server listens on all addresses.
\item[\rcitem{web}{errorlog}] Path.  The name of a file into which to
  write an error log.  By default, the \hgcmd{serve} command writes this
  information to standard error, not to a file.
\item[\rcitem{web}{ipv6}] Boolean.  Whether to use the IPv6 protocol.
  By default, IPv6 is not used. 
\item[\rcitem{web}{port}] Integer.  The TCP~port number on which the
  server should listen.  The default port number used is~8000.
\end{itemize}

\subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
  items to}

It is important to remember that a web server like Apache or
\texttt{lighttpd} will run under a user~ID that is different to yours.
CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
usually also run under that user~ID.

If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
scripts won't read that \hgrc\ file.  Those settings will thus only
affect the behaviour of the \hgcmd{serve} command when you run it.  To
cause CGI scripts to see your settings, either create a \hgrc\ file in
the home directory of the user ID that runs your web server, or add
those settings to a system-wide \hgrc\ file.


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