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:
- Registre una cuenta en https://salsa.debian.org y habilite el acceso SSH subiendo
una clave SSH pública a su cuenta. Consulte las páginas de ayuda
de Salsa para más detalles. Después puede clonar el
repositorio
webwml
con la orden:git clone git@salsa.debian.org:webmaster-team/webwml.git
- Alternativamente, puede
clonar el repositorio utilizando el protocolo HTTPS. Tenga en cuenta que
utilizando este método creará el repositorio local, pero no
podrá enviar modificaciones directamente al repositorio:
git clone https://salsa.debian.org/webmaster-team/webwml.git
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:
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
dentro del directoriowebwml
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/
- 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:
git pull
- Ahora puede empezar a editar y hacer cambios a los ficheros.
- 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"
- Si tiene acceso ilimitado de escritura al repositorio
webwml
remoto, ahora puede enviar directamente los cambios al repo de Salsa:git push
- 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:
- Modifique el fichero o ficheros originales y confirme los cambios.
- Actualice las traducciones.
- 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. - Revise los cambios (por ejemplo, con
git diff
). - Confirme los cambios de las traducciones.
Alternativamente, puede utilizar expresiones regulares para hacer varios cambios en ficheros en una única pasada:
- Ejecute
smart_change.pl -s s/FOO/BAR/ fich-orig-1 fich-orig-2 ...
- Revise los cambios (por ejemplo, con
git diff
). - Confirme los cambios en el fichero o ficheros originales.
- 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. - 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:
- Project forking workflow [«Flujo de trabajo de bifurcaciones de proyectos»]
- When you work in a fork [«Cuando trabaja en una bifurcación»]
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):
- Abra un navegador web y vaya a https://tracker.debian.org/pkg/www.debian.org.
- 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). - Vaya a https://tracker.debian.org/accounts/subscriptions, después a
modify keywords
, marquevcs
(si no está ya marcado) y grabe los cambios. - 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:
- Identifíquese en Salsa y vaya a la página del proyecto.
- Haga click en el icono con la campana en la parte superior de la página inicial del proyecto.
- Seleccione el nivel de notificación que prefiera.