Utilisation de git pour gérer le code source du site web

Introduction

Git est un système de gestion de versions qui aide à la gestion de travaux simultanés sur des documents communs par plusieurs personnes. Chaque utilisateur peut détenir une copie locale du dépôt principal. Ces copies peuvent être sur la même machine ou aux quatre coins du monde. Les utilisateurs peuvent alors modifier leur copie locale comme ils le souhaitent et, quand la version modifiée est prête, enregistrer leurs changements (« commit ») et les envoyer en retour vers le dépôt principal.

Git ne vous permettra pas d'envoyer directement une modification si le dépôt distant a reçu des modifications (commits) plus récentes que votre copie locale, dans la même branche. Dans le cas où un tel conflit survient, veuillez d'abord rechercher et appliquer les mises à jour de votre copie locale et rebaser (rebase) vos nouvelles modifications au-dessus du dernier « commit » envoyé.

Accès en écriture au dépôt de Git

La totalité du code source du site web de Debian est géré avec Git. Vous le trouverez à l'adresse https://salsa.debian.org/webmaster-team/webwml. Par défaut, les utilisateurs ne sont pas autorisés à envoyer de « commits » sur le dépôt du code source. Vous aurez besoin de certaines permissions pour obtenir un accès en écriture au dépôt.

Accès en écriture illimité

Si vous avez besoin d'un accès en écriture illimité au dépôt (par exemple, vous êtes sur le point de devenir un contributeur régulier), veuillez en faire la demande à l'aide de l'interface web https://salsa.debian.org/webmaster-team/webwml après vous être connecté à la plateforme Salsa de Debian.

Si vous débutez dans le développement du site web de Debian et si vous n'avez pas d'expérience antérieure, veuillez aussi envoyer un courriel à debian-www@lists.debian.org en vous présentant avant de demander l'accès en écriture illimité. Veuillez indiquer quelque chose d'utile dans votre présentation, comme la langue ou la partie du site web auxquelles vous voudriez contribuer, et qui pourrait se porter garant pour vous.

Écrire dans le dépôt avec des « merge requests »

Si vous n'avez pas l'intention de demander un accès en écriture illimité au dépôt ou si vous n'êtes pas à même de le faire, vous pouvez toujours soumettre une demande de fusion (« merge request ») et laisser d'autres développeurs revoir et accepter votre travail. Veuillez soumettre les « merge requests » en utilisant la procédure standard fournie par la plateforme GitLab de Salsa à travers son interface web (consultez Project forking workflow et When you work in a fork pour plus de détails.

Les demandes de fusion ne sont pas suivies par tous les développeurs du site web, elles peuvent donc ne pas être toujours traitées à temps. Si vous n'êtes pas sûr que votre contribution sera acceptée, envoyez un message à la liste de diffusion debian-www et demandez une relecture.

Travailler sur le dépôt

Obtenir une copie locale du dépôt

D'abord, vous devez installer git pour travailler avec le dépôt. Ensuite, configurez vos informations d'utilisateur et d'adresse courriel sur votre ordinateur (veuillez vous référer à la documentation générale de git pour apprendre comment le faire). Ensuite, vous pouvez cloner le dépôt (en d'autres termes, vous en faites une copie) en utilisant une de ces deux méthodes.

La façon recommandée de travailler sur webwml est d'abord d'ouvrir un compte sur salsa.debian.org et d'autoriser un accès SSH à git en envoyant une clé publique SSH dans votre compte salsa. Voir les pages d'aide de salsa pour obtenir plus de détails sur comment le faire. Vous pouvez ensuite cloner le dépôt webwml avec la commande suivante :

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

Si vous n'avez pas de compte salsa, une méthode alternative est de cloner le dépôt avec le protocole HTTPS :

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

Cela vous donnera la même copie locale du dépôt, mais vous ne serez pas capable d'envoyer directement vos modifications de cette manière.

Cloner la totalité du dépôt webwml demandera le téléchargement d'environ 500 Mo de données, cela peut donc être difficile pour tous ceux qui ont une liaison Internet lente ou instable. Vous pouvez essayer de procéder à un clonage superficiel avec d'abord une profondeur minimale pour un téléchargement initial plus court :

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

Une fois que vous avez obtenu un dépôt (superficiel) utilisable, vous pouvez approfondir la copie locale superficielle et, finalement, la convertir en un dépôt local complet :

  git fetch --deepen=1000 # approfondit le dépôt de 1000 commits supplémentaires
  git fetch --unshallow   # obtient tous les commits manquants, convertit le dépôt en dépôt complet

Récupération partielle de contenu

Vous pouvez procéder à la récupération de seulement un sous-ensemble des pages ainsi :

   $ git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
   $ cd webwml
   $ git config core.sparseCheckout true
Dans webwml : créez le fichier .git/info/sparse-checkout avec un contenu comme celui-ci (si vous ne voulez que les fichiers de base, l'anglais et les traductions en français et en espagnol) :
      /*
      !/[a-z]*/
      /english/
      /french/
      /spanish/
puis :
   $ git checkout --

Soumettre des modifications locales

Garder à jour le dépôt local

De temps en temps (et au moins avant de débuter un travail d'édition !) il faudra lancer la commande

   git pull

pour récupérer tous les fichiers du dépôt qui ont changé.

Il est fortement recommandé de garder propre son répertoire local de travail de git avant d'exécuter la commande « git pull » et de poursuivre le travail d'édition. Si vous avez des modifications qui n'ont pas fait l'objet de commits ou des commits locaux qui ne sont pas dans le dépôt distant dans la branche courante, exécuter « git pull » créera immédiatement des demandes de fusion ou même échouera dû à des conflits. Vous devriez envisager de garder votre travail inachevé dans une autre branche ou d'utiliser des commandes telles que « git stash ».

Attention : git est un système de contrôle de versions distribué (non centralisé). Cela signifie que quand vous préparez l'envoi de vos modifications, elles seront seulement stockées dans votre dépôt local. Pour les partager avec d'autres, vous devrez aussi envoyer vos modifications vers le dépôt central de Salsa.

Exemple de modifications de fichiers anglais

Un exemple de la manière dont des fichiers anglais peuvent être modifiés dans le dépôt source du site web est fourni ici. Après avoir obtenu une copie locale du dépôt avec la commande « git clone » et avant de commencer le travail de modification, exécutez la commande suivante :

   $ git pull

Maintenant, modifiez les fichiers. Quand c'est fait, préparez l'envoi de vos modifications dans votre dépôt local avec les commandes :

   $ git add chemin/vers/fichier(s)
   $ git commit -m "Votre message d'envoi"

Si vous avez un accès en écriture illimité au dépôt webwml distant, vous pouvez maintenant envoyer vos modifications dans le dépôt de Salsa :

   $ git push

Si vous n'avez pas un accès en écriture direct au dépôt webwml, vous devez envisager de soumettre vos modifications en utilisant la fonction « Merge Request » telle qu'elle est fournie par la plateforme GitLab de Salsa ou en sollicitant l'aide d'autres développeurs.

Il s'agit d'un résumé très sommaire de la façon d'utiliser git pour manipuler le code source du site web de Debian. Pour plus d'informations sur git, veuillez consulter sa documentation.

Fermer des bogues de Debian dans les envois de git

En incluant Closes: #nnnnnn dans votre entrée de journal d'envoi, le bogue nnnnnn sera fermé automatiquement quand vous enverrez vos modifications. La forme exacte est la même que celle décrite dans la Charte Debian.

Connexion en utilisant HTTP/HTTPS

Beaucoup de sites web de Debian prennent en charge SSL/TLS, veuillez donc utiliser des liens en HTTPS lorsque c'est possible et pertinent. Néanmoins, certains sites web de Debian, DebConf, SPI, etc., ne prennent pas en charge HTTPS ou n'ont leur certificat SSL signé que par SPI, (et pas par une autorité SSL considérée de confiance par tous les navigateurs). Veuillez éviter les liens en HTTPS vers ces sites web pour que les visiteurs ne reçoivent pas de messages d'erreur.

Le dépôt git rejettera les envois contenant des liens en HTTP pur vers les sites web Debian qui prennent en charge HTTPS, ou contenant des liens en HTTPS vers les sites web Debian, DebConf et SPI qui sont connus pour ne pas prendre en charge HTTPS ou avoir un certificat signé uniquement par SPI.

Travailler sur des traductions

Les traductions doivent être toujours tenues à jour avec les fichiers anglais correspondants. L'en-tête translation-check des fichiers traduits est utilisé pour suivre la version des fichiers anglais sur laquelle elles reposent. Si vous modifiez des fichiers traduits, il est nécessaire de mettre à jour l'en-tête translation-check pour qu'il corresponde à l'empreinte de la modification correspondante du fichier anglais. Vous pouvez trouver cette empreinte avec la commande suivante :

$ git log chemin/vers/fichier/en_anglais/

Si vous faites une nouvelle traduction de fichier, veuillez utiliser le script copypage.pl et il créera un modèle pour votre langue, y compris l'en-tête de traduction correct.

Modifications de traductions avec smart_change.pl

smart_change.pl est un script conçu pour faciliter la mise à jour à la fois des fichiers originaux et de leurs traductions. Il y a deux façons de l'utiliser, selon les modifications que vous faites.

Pour utiliser smart_change afin de mettre à jour seulement les en-têtes « translation-check » quand vous travaillez manuellement sur les fichiers :

  1. modifiez le ou les fichiers originaux et envoyez les modifications ;
  2. mettez à jour les traductions ;
  3. exécutez smart_change.pl : le script récupérera les modifications et mettra à jour les en-têtes dans les fichiers de traduction ;
  4. vérifiez les modifications (par exemple avec « git diff ») ;
  5. envoyez les modifications de traduction.

Sinon, si vous utilisez smart_change avec une expression rationnelle pour faire plusieurs modifications dans plusieurs fichiers en une seule passe :

  1. exécutez smart_change.pl -s s/toto/titi/ fichier_origine1 fichier_origine2 ... ;
  2. vérifiez les modifications (par exemple avec « git diff ») ;
  3. envoyez les fichiers originaux ;
  4. exécutez smart_change.pl fichier_origine1 fichier_origine2 (c'est-à-dire sans l'expression rationnelle cette fois-ci) ; cela mettra à jour uniquement les en-têtes dans les fichiers traduits ;
  5. finalement, envoyez les modifications de traduction.

C'est plus compliqué qu'auparavant (deux envois sont nécessaires), mais inévitable vue la manière dont fonctionnent les empreintes d'envoi de git.

Obtenir des notifications

Recevoir des notifications de modification

Nous avons configuré le projet webwml dans Salsa, de telle manière que les modifications apparaissent sur le canal IRC #debian-www.

Si vous voulez recevoir des notifications par courriel lorsqu'il y a des modifications dans le dépôt de webwml, veuillez vous abonner au pseudo-paquet www.debian.org au moyen de tracker.debian.org et activez-y le mot clé vcs, en suivant ces étapes (une seule fois) :

Recevoir des notifications de Merge Request

Si vous voulez recevoir des notifications par courriel lorsqu'il y a de nouvelles requêtes de fusion soumises sur l'interface web du dépôt webwml de la plateforme GitLab de Salsa, vous pouvez configurer les réglages de notification du dépôt webwml sur l'interface web, en suivant ces étapes :