Uso de los repositorios de desarrollo (bajo control de versiones con Mercurial)

¿Para qué sirve el control de versiones?

Un sistema de control de versiones (Version Control System o VCS  en inglés) permite llevar cuenta del historial de cambios de una colección de archivos, como es un proyecto de software, un libro o un dibujo. Anteriormente, en Alqua publicábamos un paquete comprimido (.zip) por cada versión de un documento, lo que tenía varios inconvenientes. Entre otros:

• Las personas interesadas sólo pueden acceder a estas "versiones oficiales" que nosotros empaquetamos y subimos manualmente al servidor de Alqua.
  
• Cada paquete contiene todos los archivos de una misma versión de cada documento, de manera que hay gran cantidad de datos duplicados.
• Para ver qué los cambios de una versión y otra de un mismo documento hay que compararlos manualmente. Del mismo modo, es difícil combinar cambios procedentes de distintos autores, pues mientras uno edita el documento todos los demás deben abstenerse.

Un sistema de control de versiones soluciona todos estos problemas y además tiene otras ventajas, ya que:

• Sólo es necesario subir al servidor los datos de los archivos que han cambiado y se puede hacer de manera frecuente con facilidad, de manera que los interesados pueden seguir de cerca el proceso de desarrollo.
  
• Sólo se almacenan los cambios en los archivos entre las distintas versiones, así que no existe apenas duplicidad de datos.
• Se puede ver fácilmente qué es lo que ha cambiado entre una versión y otra un documento, y se puede obtener una copia completa de cualquier versión pasada.
  
• Permite que se desarrollen varias versiones en paralelo de un mismo documento y después mezclarlas.

Para más información sobre cómo funciona el control de versiones, recomendamos la lectura de A visual guide to version control.

¿En qué consiste el control de cambios distribuído?

Antiguamente, muchos sistemas de control de cambios funcionaban de manera centralizada, es decir, el origen de datos canónico se encontraba en un servidor, y cualquier cambio que se hiciese en los datos tenía que enviarse a ese servidor principal para poder ser controlado.

Los sistemas de control de cambios centralizados aún se usan en muchísimos proyectos, porque son simples, estables, y en la mayoría de los casos adecuados para el proyecto en cuestión. Sin embargo, en los últimos años muchos proyectos están migrando hacia sistemas de control de cambios distribuidos.

Como su propio nombre indica, el principal cambio es que el sistema es distribuido: los autores ya no tienen que enviar sus cambios necesariamente al servidor principal, sino que cada uno tiene su propia copia local del repositorio de datos y pueden intercambiar datos entre ellos sin pasar por el servidor principal. De esta manera, los autores pueden colaborar entre ellos de forma independiente y sin necesidad de estar conectados a Internet.

Para más información sobre cómo funciona el control de cambios distribuido y una introducción a Mercurial, recomendamos encarecidamente leer Intro to Distributed Version Control (Illustrated).

Vale, ya sé en qué consiste pero, ¿cómo lo uso?

Instalar Mercurial

En Alqua utilizamos un sistema de control de versiones llamado Mercurial (abreviado Hg).

En primer lugar, debes descargar e instalar Hg, disponible para los sistemas operativos más difundidos: Windows, MacOSX y GNU/Linux. Puedes hacerlo desde la página web de Mercurial.

Si tienes algún problema con la instalación, no dudes en contactar con nosotros para que podamos ayudarte.

Aprender a utilizar Hg

Para poder entender la terminología, comandos y método de trabajo de Hg no tienes que leerte ningún libro de cientos de páginas. Tan solo es necesario que sigas algún tutorial sencillo, por ejemplo, el de la propia página de Hg en español.

Trabajar con un documento

Una vez hayas instalado y entendido a grandes rasgos cómo funciona Hg, lo primero que tienes que hacer es clonar el repositorio del documento sobre el que quieres trabajar. Para ello ejecuta

hg clone http://hg.alqua.org/<shorttitle>

donde <shorttitle> es el nombre corto del documento, por ejemplo, IFC2 o LAG. Esto descargará todos los archivos del repositorio y los colocará en una carpeta con el nombre shorttitle, que es el nombre del repositorio también.

Tras esto, sólo tienes que trabajar con los archivos igual que lo harías normalmente, recordando que no tienes que preocuparte de no sobreescribir los archivos antiguos en ningún caso. Sólo tienes que tener en cuenta una serie de cosas:

• Si añades un archivo al documento (por ejemplo, una imagen), tienes que indicarle a Hg que lo incluya en su control de cambios. Para ello, ejecuta
  

  hg add <nombre_del_archivo>

• Igualmente, para dejar de controlar un archivo no basta con borrarlo de tu disco duro, sino que tienes que indicárselo a Hg:
  

  hg rm <nombre_del_archivo>
  

• Si quieres cambiar el nombre a un archivo, no lo hagas directamente, porque Hg pensará que has borrado un archivo y creado otro. En vez de eso, ejecuta
  

  hg mv <nombre_inicial> <nombre_final>

Cuando hayas cambiado una serie de archivos en tu documento y se puedan englobar como una nueva revisión (el conjunto de los cambios está vinculado por una lógica interna, por ejemplo, un cambio de notación que afecta a varios ficheros), ejecuta

hg commit -m "<descripción de los cambios que se han hecho>"

Al hablar de revisión no nos referimos a una nueva versión del documento lista para publicarse en Alqua, sino a una serie de cambios que se puedan colocar bajo un mismo título. Unos ejemplos podrían ser "reordenación de capítulos" o "corregidas las erratas del problema del péndulo".

Según vas haciendo esto, tu repositorio local irá cambiando, pero ¿cómo compartir los nuevos cambios con los otros autores? Para ello una posibilidad es subir los cambios al repositorio visible públicamente que te ofrece Alqua (para obtener un nombre de usuario y contraseña, escríbenos un mensaje de correo electrónico solicitándolo)

hg push http://hg.alqua.org/<nombre del repositorio>

Análogamente, cuando quieras examinar cambios introducidos por otros autores y compartidos por esta vía ejecutarás

hg pull http://hg.alqua.org/<nombre del repositorio>

Con eso los cambios están en tu repositorio local, pero no en tu directorio de trabajo (copiarlos ahí directamente sería muy violento, primero tienes que decidir si los quieres). Para integrarlos en el directorio de trabajo ejecuta simplemente

hg update

Publicar una nueva versión del documento en Alqua

Cuando creas que tienes lista una nueva versión, es decir un del documento para publicarla en Alqua, sigue los siguientes pasos:

1. Asegúrate de que has guardado todos los cambios en tu repositorio local. Utiliza hg status para comprobarlo, y hg commit si necesitas guardar algo.
2. Etiqueta la versión con el número que hayas puesto en la ficha YAML del documento. Para ello, ejecuta
   

   hg tag <número de la versión>
   

   Por ejemplo:

   hg tag 0.9.1

3. Envía los cambios al repositorio de Alqua:
   

   hg push http://hg.alqua.org/<nombre del repositorio>
   

   El nombre del repositorio es el nombre corto del documento. Si no estás seguro, entra en http://hg.alqua.org y búscalo bajo la columna Name.
   Te pedirá tu nombre de usuario y tu contraseña, que son necesarios para poder escribir los cambios en el repositorio.

4. Envíanos un mensaje para avisarnos de que has publicado una nueva versión de las fuentes. Nosotros generaremos la versión en PDF del documento y la colgaremos en la página web en cuanto podamos.