Uso de los repositorios Mercurial

¿Para qué sirve el control de versiones?

El control de versiones es un sistema que te permite llevar un control de una serie de archivos para saber su historial de cambios a lo largo del tiempo. Anteriormente, en Alqua publicábamos un paquete ZIP por cada versión de un documento, lo que tenía varios inconvenientes, como:

• Tener que generar ese paquete ZIP y subirlo al servidor de Alqua
• Cada paquete contiene todos los archivos de una misma versión de cada documento, de manera que había un montón de datos duplicados, archivos que no cambiaban entre versiones, como pueden ser algunas figuras.
• No era sencillo ver qué es lo que había cambiado entre una versión y otra de un mismo documento, ni hacer mezclas entre versiones.

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

• No hace falta generar ningún paquete, y sólo es necesario subir al servidor los datos de los archivos que han cambiado.
• Sólo se almacenan los cambios en los archivos entre las distintas versiones, de manera 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.
• 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 distribuido?

Antiguamente, muchos sistemas de control de cambios funcionaban de manera centralizada, es decir, el servidor 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 del repositorio (shorttitle).

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 versión en el sistema de control, ejecuta

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

Al hablar de "versión en el sistema de control" 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".

Publicar una nueva versión del documento en Alqua

Cuando creas que tienes lista una nueva versión 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 st 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 dde 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.
   

Obtención de permiso de escritura en el repositorio de un documento

Para obtenerlo, escríbenos un mensaje de correo electrónico solicitándolo.