Uso de git para manipular el código fuente del sitio web

Introducción

Git es un sistema de control de versiones que ayuda a gestionar el hecho de que varias personas trabajen simultáneamente en el mismo material. Cada usuario puede tener una copia local del repositorio principal. Las copias locales pueden estar en la misma máquina o repartidas por todo el mundo. Los usuarios pueden modificar la copia local como deseen y, cuando el material modificado está listo, confirmar los cambios y enviarlos al repositorio principal.

Git no le permite enviar directamente los cambios si el repositorio remoto contiene alguna modificación en la misma rama hecha con posterioridad al momento en que usted hizo su copia local. Cuando se encuentre un conflicto de este tipo, actualice su copia local a partir del repositorio remoto y reorganícela (rebase) aplicando sus cambios a partir del último cambio confirmado en el repositorio remoto.

Acceso de escritura al repositorio Git

El código fuente del sitio web Debian se gestiona, en su totalidad, con Git. Se encuentra 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. Necesitará 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), considere solicitar 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, envíe también un correo electrónico a debian-www@lists.debian.org presentándose antes de solicitar acceso ilimitado de escritura. Proporcione algo útil en su presentación, como en qué idioma o en qué parte del sitio web tiene pensado trabajar y quién respondería por usted.

Escribir en el repositorio mediante solicitudes de fusión («Merge Requests»)

Si no desea obtener acceso ilimitado de escritura al repositorio o no puede hacerlo, siempre puede realizar una solicitud de fusión para que otros desarrolladores revisen y acepten su trabajo. Por favor, haga las solicitudes de fusión siguiendo el procedimiento estándar proporcionado por la plataforma GitLab de Salsa a través de su interfaz web (consulte Project forking workflow [«Flujo de trabajo de bifurcaciones de proyectos»] y When you work in a fork [«Cuando trabaja en una bifurcación»] para los detalles).

No todos los desarrolladores del sitio web monitorizan las solicitudes de fusión, por lo que es posible que estas no sean siempre atendidas con prontitud. Si no tiene la seguridad de que su contribución vaya a ser aceptada, envíe un correo electrónico a la lista de correo debian-www y solicite una revisión.

Trabajar con el repositorio

Obtención de una copia local del repositorio

Primero, necesita instalar git para trabajar con el repositorio. A continuación, configure los detalles de su usuario y de su dirección de correo electrónico en su computadora (consulte la documentación general de git para saber cómo hacerlo). Después, puede clonar el repositorio (es decir, hacer una copia local del mismo) de una de las dos maneras que describimos a continuación.

La forma recomendada de trabajar en webwml es registrando primero una cuenta en salsa.debian.org y habilitando el acceso git SSH, para lo que necesita subir una clave pública SSH a su cuenta. Vea las páginas de ayuda de Salsa para más detalles sobre cómo hacer esto. Después, puede clonar el repositorio de webwml con la orden:

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

Si no tiene una cuenta en Salsa, un método alternativo es clonar el repositorio utilizando el protocolo HTTPS:

  git clone https://salsa.debian.org/webmaster-team/webwml.git

Utilizando este método obtendrá la misma copia local, pero no podrá enviar modificaciones directamente al repositorio.

El clonado de todo el repositorio de webwml conlleva la descarga de unos 500MB de datos, lo que puede ser difícil para quien disponga de una conexión a Internet lenta o inestable. Si es este su caso, puede probar el clonado superficial con una profundidad mínima al principio 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 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

Contenido parcial en la copia de trabajo

Puede crear una copia de trabajo que contenga solo un subconjunto de las páginas de la siguiente manera:

   $ git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
   $ cd webwml
   $ git config core.sparseCheckout true
   Cree el fichero .git/info/sparse-checkout en webwml con un contenido como el siguiente
   (si solo quiere los ficheros base, las páginas en inglés y las traducciones a catalán y español):
      /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
   Después:
   $ 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 aquellos ficheros del repositorio que hayan cambiado.

Le recomendamos encarecidamente que tenga su directorio de trabajo git local limpio antes de ejecutar "git pull" y de realizar el trabajo de edición subsiguiente. 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 de edición de ficheros en inglés

A continuación proporcionamos un ejemplo de cómo editar ficheros en inglés en el repositorio del código fuente del sitio web. Tras obtener una copia local del repo utilizando "git clone", y antes de empezar el trabajo de edición, ejecute la orden siguiente:

   $ git pull

Ahora haga las modificaciones en los ficheros. Cuando haya terminado, confirme los cambios en su repositorio local con:

   $ git add ruta/al(os)/fichero(s)
   $ git commit -m "Su mensaje para este commit"

Si tiene acceso ilimitado de escritura al repositorio remoto webwml, ahora puede enviar directamente los cambios al repo de Salsa:

   $ git push

Si no tiene acceso directo de escritura al repositorio webwml, considere enviar los cambios a través de la función de solicitud de fusión («Merge Request») proporcionada por la plataforma GitLab de Salsa o pedir ayuda a otros desarrolladores.

Este es un resumen muy básico de cómo usar git para manipular el código fuente del sitio web de Debian. Para más información, consulte la documentación de git.

Cierre de bugs de Debian en commits git

Si incluye el texto Closes: #nnnnnn en la entrada del historial de confirmaciones correspondiente a su commit, el bug número #nnnnnn se cerrará cuando envíe los cambios. El formato preciso de esto 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ían todos los navegadores). Para evitar que los usuarios no pertenecientes a 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:

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

Si hace una traducción nueva de un fichero, utilice el script copypage.pl. Este script creará una plantilla para su idioma, incluyendo la cabecera translation 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.

Para utilizar smart_change con el único fin de actualizar las cabeceras translation-check cuando está trabajando manualmente en los ficheros:

  1. Haga los cambios al fichero o ficheros originales, y confírmelos.
  2. Actualice las traducciones.
  3. Ejecute smart_change.pl. 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.

O para utilizar smart_change con una expresión regular 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 procedimiento es más laborioso que el anterior (necesita dos confirmaciones), pero resulta inevitable debido a la manera en que funcionan los hashes de los commits en git.

Obtener notificaciones

Recibir notificación 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 cuando se hagan confirmaciones en el repo de webwml, suscríbase al pseudopaquete www.debian.org por medio de tracker.debian.org y active allí la palabra clave vcs siguiendo estos pasos (solo una vez):

Recibir notificación de las solicitudes de fusión («Merge Request»)

Si desea recibir un correo electrónico de notificación cada vez que se realice una nueva solicitud de fusión en el repositorio webwml a través de la interfaz web de la plataforma GitLab de Salsa, puede modificar la configuración de notificaciones para el repositorio webwml en la interfaz web siguiendo estos pasos: