Utilisation de Git pour travailler sur le site web de Debian

Travailler sur le dépôt Git

Entrons dans le vif du sujet — dans cette partie, vous apprendrez comment créer une copie locale du dépôt principal, comment garder votre dépôt local à jour et comment soumettre votre travail. Nous vous expliquerons aussi comment travailler sur les traductions.

Obtenir une copie locale

D'abord, installez Git. Ensuite, configurez Git et entrez votre nom et votre adresse courriel. Si vous êtes un nouvel utilisateur de Git, c'est sans doute une bonne idée de lire la documentation générale de Git en premier.

La prochaine étape est de cloner le dépôt (autrement dit, créer une copie locale du dépôt). Il y a deux manières de le faire :

Astuce : Cloner la totalité du dépôt webwml demandera le téléchargement d'environ 1,3 Go de données, ce qui pourrait être trop si vous avez une liaison Internet lente ou instable. Donc, il est possible de définir 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 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

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

  1. git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
  2. cd webwml
  3. git config core.sparseCheckout true
  4. Créez le fichier .git/info/sparse-checkout dans le répertoire webwml pour définir le contenu que vous voulez récupérer. Par exemple, si vous ne voulez que les fichiers de base, l'anglais et les traductions en français et en espagnol, le ficher devra ressembler à cela : 
          /*
      !/[a-z]*/
      /english/
      /french/
      /spanish/
  5. Enfin, vous pouvez récupérer le dépôt : git checkout --

Soumettre des modifications locales

Garder à jour le dépôt local

De temps en temps (et sans aucun doute 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

Regardons un exemple pratique et une session de travail typique. Considérons que vous avez obtenu une copie locale du dépôt avec la commande git clone. Les étapes suivantes sont :

  1. git pull
  2. Maintenant vous pouvez commencer à éditer et modifier les fichiers.
  3. 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"
  4. Si vous avez un accès en écriture illimité au dépôt webwml distant, vous pouvez maintenant envoyer directement vos modifications dans le dépôt de Salsa : git push
  5. Si vous n'avez pas un accès en écriture direct au dépôt webwml, soumettez vos modifications en utilisant la fonction merge request ou sollicitez l'aide d'autres développeurs.

Fermer des bogues de Debian dans les envois de Git

En incluant Closes: #nnnnnn dans votre entrée de journal d'envoi, le bogue nº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 utilisateurs en dehors de Debian 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.

Voici comment utiliser smart_change.pl et comment 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 -c COMMIT_HASH (utiliser l'empreinte des modifications dans les fichiers originaux). 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.

Autrement, vous pouvez travailler 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.

Il faut reconnaître que c'est plus compliqué qu'avec le premier exemple (deux envois sont nécessaires), mais inévitable vue la manière dont fonctionnent les empreintes d'envoi de Git.

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

Le code source du site web de Debian est géré avec Git et situé à l'adresse https://salsa.debian.org/webmaster-team/webwml. Par défaut, les invités (guest) ne sont pas autorisés à envoyer de « commits » sur le dépôt du code source. Si vous souhaitez contribuer au site web de Debian, 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é. Pourriez-vous avoir la gentillesse d'en dire plus sur vous comme la partie du site web à laquelle vous voudriez contribuer ou quelles langues vous parlez, et aussi s'il y a un autre membre de l'équipe Debian qui pourrait se porter garant de vous.

Demandes de fusion

Il n'est pas indispensable d'obtenir un accès en écriture illimité au dépôt — 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 et consulter les deux documents suivants :

Veuillez noter que les demandes de fusion ne sont pas suivies par tous les développeurs du site web. Il se pourrait donc que cela prenne quelque temps avant que vous receviez un commentaire. 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.

Recevoir des notifications

Si vous travaillez sur le site web de Debian, vous voulez sans doute savoir ce qui se passe dans le dépôt webwml. Il y a deux manières de se tenir au courant : les notifications de modification et les notifications de requête de fusion.

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 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) :

  1. ouvrez un navigateur web et allez à l'adresse https://tracker.debian.org/pkg/www.debian.org ;
  2. abonnez-vous au pseudo-paquet www.debian.org (vous pouvez vous authentifier par SSO ou enregistrer une adresse courriel et un mot de passe, si vous n'utilisez pas déjà tracker.debian.org avec un autre objectif) ;
  3. allez à la page https://tracker.debian.org/accounts/subscriptions, puis à modify keywords, cochez vcs (si ce n'est pas déjà fait) et sauvegardez ;
  4. à partir de ce moment, vous recevrez des courriels lorsque quelqu'un enverra une modification dans le dépôt webwml.

Recevoir des notifications de requête de fusion

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

  1. connectez-vous à votre compte Salsa et allez sur la page du projet ;
  2. cliquez sur l'icône cloche en haut de la page d'accueil du projet ;
  3. choisissez le niveau de notification que vous préférez.