Uso de Git para trabajar en el sitio web de Debian

Trabajar con el repositorio Git

Entremos directamente en materia. En esta sección aprenderá cómo hacer una copia local del repositorio principal, cómo mantenerla actualizada y cómo enviar su trabajo. También explicaremos cómo trabajar en las traducciones.

Obtención de una copia local

Primero instale Git. A continuación configure Git e introduzca su nombre y su dirección de correo electrónico. Si no ha trabajado antes con Git, probablemente sea buena idea que empieze por consultar la documentación general de Git.

El siguiente paso es clonar el repositorio (es decir: hacer una copia local del mismo). Hay dos maneras de hacerlo:

Un consejo: Clonar el repositorio webwml completo conlleva la descarga de unos 1,3 GB de datos, lo que podría ser demasiado si utiliza una conexión a Internet lenta o inestable. Si es este su caso, puede definir una profundidad mínima para que la descarga inicial sea menor: 

  git clone git@salsa.debian.org:webmaster-team/webwml.git --depth 1

Tras obtener un repositorio (superficial) utilizable, puede ir aumentando la profundidad de la copia local y, finalmente, convertirla en un repositorio local completo:

  git fetch --deepen=1000 # aumenta la profundidad del repo con otros 1000 commits
  git fetch --unshallow   # descarga todos los commits que faltan, convierte el repo en un repo completo

También puede extraer solo un subconjunto de las páginas:

  1. git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
  2. cd webwml
  3. git config core.sparseCheckout true
  4. Cree el fichero .git/info/sparse-checkout dentro del directorio webwml para definir el contenido que quiere extraer. Por ejemplo, si solo quiere extraer los ficheros base, las páginas en inglés y las traducciones a catalán y español, el fichero tendrá este aspecto: 
          /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
  5. Por último, puede crear la copia de trabajo con: git checkout --

Envío de cambios locales

Mantener actualizado su repo local

Cada pocos días (y, desde luego, ¡antes de empezar a modificar algo!) debería ejecutar:

  git pull

para descargar los ficheros del repositorio que hayan cambiado.

Le recomendamos encarecidamente que tenga su directorio de trabajo Git local limpio antes de ejecutar git pull y empezar a editar ficheros. Si tiene cambios sin confirmar o cambios confirmados localmente en la rama actual pero no incluidos en el repositorio remoto, la ejecución de git pull creará automáticamente commits de fusión o incluso fallará debido a conflictos. Considere mantener su trabajo en curso en otra rama o utilizar órdenes como git stash.

Nota: Git es un sistema de control de versiones distribuido (no centralizado). Esto significa que cuando confirma cambios, estos cambios solo se almacenan en su repositorio local. Para compartirlos con otros, además, tiene que enviar sus cambios al repositorio central alojado en Salsa.

Ejemplo: edición de ficheros

Veamos un ejemplo práctico de una típica sesión de edición. Supondremos que ya ha obtenido una copia local del repo con git clone. Los pasos siguientes serían:

  1. git pull
  2. Ahora puede empezar a editar y hacer cambios a los ficheros.
  3. Cuando haya terminado, confirme los cambios en su repositorio local: 
        git add ruta/al(os)/fichero(s)
    git commit -m "Su mensaje para este commit"
  4. Si tiene acceso ilimitado de escritura al repositorio webwml remoto, ahora puede enviar directamente los cambios al repo de Salsa: git push
  5. Si no tiene acceso directo de escritura al repositorio webwml, envíe los cambios mediante una solicitud de fusión («merge request») o póngase en contacto con otros desarrolladores y pídales ayuda.

Cierre de fallos de Debian en commits de Git

Si incluye el texto Closes: #nnnnnn en la entrada del historial de confirmaciones correspondiente a su commit, el fallo número #nnnnnn se cerrará cuando envíe los cambios. El formato preciso es el mismo que en las normas de Debian.

Uso de HTTP/HTTPS en los enlaces

Muchos sitos web de Debian soportan SSL/TLS. Use enlaces HTTPS cuando sea posible y razonable. Sin embargo, algunos sitios web de Debian/DebConf/SPI/etc, o bien no tienen soporte HTTPS, o bien utilizan solo la autoridad certificadora de SPI (y no una autoridad certificadora SSL en la que confíen todos los navegadores). Para evitar que los usuarios que no utilizan Debian obtengan mensajes de error, no incluya enlaces a esos sitios utilizando HTTPS.

El repositorio Git rechazará tanto los commits que contengan enlaces HTTP a los sitios web de Debian que soportan HTTPS como los que contengan enlaces HTTPS a los sitios web de Debian/DebConf/SPI que se sabe que, o bien no soportan HTTPS, o bien usan certificados firmados únicamente por SPI.

Trabajo con traducciones

Las traducciones deberían mantenerse siempre actualizadas con relación al fichero en inglés correspondiente. La cabecera translation-check en los ficheros traducidos se usa para indicar en qué versión del fichero en inglés está basado el fichero traducido actual. Si modifica ficheros traducidos, tiene que actualizar la cabecera translation-check para que coincida con el hash del commit Git de la modificación correspondiente en el fichero en inglés. Puede obtener dicho hash con la orden:

  git log ruta/al/fichero/en/inglés

Si hace una traducción nueva de un fichero, utilice el script copypage.pl. Este script crea una plantilla para su idioma, incluyendo la cabecera de traducción correcta.

Modificación de traducciones con smart_change.pl

smart_change.pl es un script diseñado para facilitar la actualización, de forma conjunta, de ficheros originales y de sus traducciones. Hay dos maneras de usarlo, dependiendo de los cambios que esté haciendo.

Esta es la forma de utilizar smart_change.pl y de actualizar las cabeceras translation-check cuando está trabajando manualmente en los ficheros:

  1. Modifique el fichero o ficheros originales y confirme los cambios.
  2. Actualice las traducciones.
  3. Ejecute smart_change.pl -c COMMIT_HASH (use el hash del commit de los cambios en el fichero o ficheros originales). El script recogerá los cambios y actualizará las cabeceras de los ficheros traducidos.
  4. Revise los cambios (por ejemplo, con git diff).
  5. Confirme los cambios de las traducciones.

Alternativamente, puede utilizar expresiones regulares para hacer varios cambios en ficheros en una única pasada:

  1. Ejecute smart_change.pl -s s/FOO/BAR/ fich-orig-1 fich-orig-2 ...
  2. Revise los cambios (por ejemplo, con git diff).
  3. Confirme los cambios en el fichero o ficheros originales.
  4. Ejecute smart_change.pl fich-orig-1 fich-orig-2 (esta vez sin la expresión regular). Ahora solo actualizará las cabeceras de los ficheros traducidos.
  5. Finalmente, confirme los cambios de las traducciones.

Este segundo ejemplo requiere algo más de esfuerzo que el primero ya que supone hacer dos commits, pero resulta inevitable debido a la manera en que funcionan los hashes de los commits en Git.

Acceso de escritura al repositorio Git

El código fuente del sitio web de Debian se gestiona con Git y se encuentra alojado en https://salsa.debian.org/webmaster-team/webwml. Por omisión, no se permite que los visitantes envíen cambios al repositorio del código fuente. Si quiere contribuir al sitio web de Debian, necesita algún tipo de permiso para tener acceso de escritura al repositorio.

Acceso ilimitado de escritura

Si necesita acceso ilimitado de escritura al repositorio (por ejemplo, si va a contribuir con frecuencia), solicite acceso de escritura a través de la interfaz web https://salsa.debian.org/webmaster-team/webwml tras identificarse en la plataforma Salsa de Debian.

Si no ha participado antes en el desarrollo del sitio web de Debian y no tiene experiencia previa, envíe también un correo electrónico a debian-www@lists.debian.org presentándose antes de solicitar acceso ilimitado de escritura. Si es tan amable cuéntenos algo sobre usted como, por ejemplo, en qué parte del sitio web tiene pensado trabajar, qué idiomas habla y si hay algún miembro de un equipo Debian que pueda responder por usted.

Solicitudes de fusión («Merge Requests»)

No es necesario obtener acceso ilimitado de escritura al repositorio, siempre puede realizar una solicitud de fusión para que otros desarrolladores revisen y acepten su trabajo. Siga el procedimiento estándar para las solicitudes de fusión proporcionado por la plataforma GitLab de Salsa a través de su interfaz web y consulte estos dos documentos:

Tenga en cuenta que no todos los desarrolladores del sitio web monitorizan las solicitudes de fusión. En consecuencia, podría pasar un tiempo antes de que tenga noticias. Si tiene dudas sobre si su contribución será aceptada o no, puede enviar un correo electrónico a la lista de correo debian-www y pedir una revisión de su solicitud.

Recibir notificaciones

Si está trabajando en el sitio web de Debian, es posible que quiera estar al tanto de la actividad en el repositorio webwml. Hay dos herramientas para mantenerse informado: notificaciones de confirmaciones y notificaciones de solicitudes de fusión.

Recibir notificaciones de las confirmaciones

Hemos configurado el proyecto webwml en Salsa de forma que las confirmaciones se muestren en el canal IRC #debian-www.

Si quiere recibir notificaciones por correo electrónico sobre confirmaciones en el repo de webwml, suscríbase al pseudopaquete www.debian.org a través de tracker.debian.org y active allí la palabra clave vcs siguiendo estos pasos (solo una vez):

  1. Abra un navegador web y vaya a https://tracker.debian.org/pkg/www.debian.org.
  2. Suscríbase al pseudopaquete www.debian.org. (Puede identificarse mediante SSO o registrar una dirección de correo electrónico y una contraseña si no está usando ya tracker.debian.org para otros fines).
  3. Vaya a https://tracker.debian.org/accounts/subscriptions, después a modify keywords, marque vcs (si no está ya marcado) y grabe los cambios.
  4. A partir de este momento recibirá correos electrónicos cuando alguien confirme cambios en el repo webwml.

Recibir notificaciones de las solicitudes de fusión

Si desea recibir correos electrónicos de notificación cada vez que se realice una nueva solicitud de fusión en el repositorio webwml de Salsa, puede modificar la configuración de notificaciones en la interfaz web siguiendo estos pasos:

  1. Identifíquese en Salsa y vaya a la página del proyecto.
  2. Haga click en el icono con la campana en la parte superior de la página inicial del proyecto.
  3. Seleccione el nivel de notificación que prefiera.