Envoyer des correctifs (Manuel de référence de GNU Guix)

22.10 Envoyer des correctifs

Le développement se fait avec le système de contrôle de version Git. Ainsi, l’accès au dépôt n’est pas strictement nécessaire. Nous accueillons les contributions sous forme de correctifs produits par git format-patch envoyés sur la liste de diffusion guix-patches@gnu.org (voir Submitting patches to a project dans Git User Manual). Si vous voulez contribuer, nous vous encourageons à prendre un moment pour changer quelques options du dépôt Git pour améliorer la lisibilité des correctifs avant de commencer (voir Configurer Git). Si vous avez bien expérimenté la contribution à Guix, vous pouvez aussi regarder la section sur les accès en commit (voir Accès en commit).

Cette liste de diffusion est gérée par une instance Debbugs, qui nous permet de suivre les soumissions (voir Suivi des bogues et des changements). Chaque message envoyé à cette liste se voit attribuer un nouveau numéro de suivi ; les gens peuvent ensuite répondre à cette soumission en envoyant un courriel à NUMÉRO_PROBLÈME@debbugs.gnu.org, où NUMÉRO_PROBLÈME est le numéro de suivi (voir Envoyer une série de correctifs).

Veuillez écrire les messages de commit dans le format ChangeLog (voir Change Logs dans GNU Coding Standards) ; vous pouvez regarder l’historique des commits pour trouver des exemples.

Vous pouvez aider à rendre le processus de revue plus efficace et ainsi augmenter les chances que votre correctif soit revu rapidement, en décrivant le contexte de votre correctif et l’impact qu’il pourrait avoir. Par exemple, si votre correctif corrige un paquet cassé, décrivez le problème et la manière dont votre correctif le corrige. Dites-nous comment vous avez testé votre correctif. Les personnes qui utilisent du code changé par votre correctif devront-elles ajuster leur utilisation ? Si c’est le cas, expliquez de quelle manière. En général, essayez d’imaginer les questions que vous poserait la personne qui relit votre correctif, et répondez à ces questions en avance.

Avant de soumettre un correctif qui ajoute ou modifie la définition d’un paquet, veuillez vérifier cette check-list :

Si les auteurs ou autrices du paquet logiciel fournissent une signature cryptographique pour l’archive, faites un effort pour vérifier l’authenticité de l’archive. Pour un fichier de signature GPG détaché, cela se fait avec la commande gpg --verify.
Prenez un peu de temps pour fournir un synopsis et une description adéquats pour le paquet. Voir Synopsis et descriptions pour quelques lignes directrices.
Lancez guix lint paquet, où paquet est le nom du nouveau paquet ou du paquet modifié, et corrigez les erreurs qu’il rapporte (voir Invoquer guix lint).
Lancez guix style paquet pour formater la nouvelle définition du paquet en suivant les conventions du projet (voir Invoquer guix style).
Assurez-vous que le paquet se construise sur votre plate-forme avec guix build paquet.
Nous vous recommandons aussi d’essayer de construire le paquet sur les autres plate-formes prises en charge. Comme vous n’avez pas forcément accès aux plate-formes matérielles, nous vous recommandons d’utiliser le qemu-binfmt-service-type pour les émuler. Pour cela, ajoutez le module de service virtualization et le service suivant à la liste des services dans votre configuration de système d’exploitation :
```
(service qemu-binfmt-service-type
 (qemu-binfmt-configuration
   (platforms (lookup-qemu-platforms "arm" "aarch64"))))
```
Puis reconfigurez votre système.

Vous pourrez ensuite construire les paquets pour différentes plate-formes en spécifiant l’option --system. Par exemple pour construire le paquet « hello » pour les architectures armhf ou aarch64, vous devrez lancer les commandes suivantes, respectivement :
```
guix build --system=armhf-linux --rounds=2 hello
guix build --system=aarch64-linux --rounds=2 hello
```
Assurez-vous que le paquet n’utilise pas de copie groupée d’un logiciel déjà disponible dans un paquet séparé.
Parfois, les paquets incluent des copie du code source de leurs dépendances pour le confort des utilisateur·rices. Cependant, en tant que distribution, nous voulons nous assurer que ces paquets utilisent bien les copient que nous avons déjà dans la distribution si elles existent. Cela améliore l’utilisation des ressources (la dépendance n’est construite et stockée qu’une seule fois) et permet à la distribution de faire des changements transversaux comme appliquer des correctifs de sécurité pour un paquet donné depuis un unique emplacement et qu’ils affectent tout le système, ce qu’empêchent les copies groupées.
Regardez le profil rapporté par guix size (voir Invoquer guix size). Cela vous permettra de remarquer des références à d’autres paquets qui ont été retenus sans que vous vous y attendiez. Il peut aussi aider à déterminer s’il faut découper le paquet (voir Des paquets avec plusieurs résultats) et quelles dépendances facultatives utiliser. En particulier, évitez d’ajouter texlive en dépendance : à cause de sa taille extrême, utilisez la procédure updmap.cfg à la place.
Vérifiez que les paquets qui en dépendent (s’ils existent) ne sont pas affectés par le changement ; guix refresh --list-dependant paquet vous aidera (voir Invoquer guix refresh).
Vérifiez si le processus de construction du paquet est déterministe. Cela signifie typiquement vérifier qu’une construction indépendante du paquet renvoie exactement le même résultat que vous avez obtenu, bit à bit.
Une manière simple de le faire est de reconstruire le paquet plusieurs fois à la suite sur votre machine (voir Invoquer guix build) :
```
guix build --rounds=2 mon-paquet
```
Cela est suffisant pour trouver une classe de non-déterminisme commune, comme l’horodatage ou des sorties générées aléatoirement dans le résultat de la construction.

Une autre option consiste à utiliser guix challenge (voir Invoquer guix challenge). Vous pouvez lancer la commande une fois que les paquets ont été committés et construits par bordeaux.guix.gnu.org pour vérifier s’il obtient le même résultat que vous. Mieux encore : trouvez une autre machine qui peut le construire et lancez guix publish. Puisque la machine distante est sûrement différente de la vôtre, cela peut trouver des problèmes de non-déterminisme liés au matériel — par exemple utiliser une extension du jeu d’instruction — ou du noyau du système d’exploitation — par exemple se reposer sur uname ou les fichiers de /proc.
Lorsque vous écrivez de la documentation, utilisez une formulation au genre neutre lorsque vous vous référez à des personnes, comme le “they”, “their”, “them” singulier (en anglais).
Vérifiez que votre correctif contienne seulement un ensemble de changements liés. Grouper des changements non liés ensemble rend la revue plus difficile et plus lente.
Ajouter plusieurs paquet ou une mise à jour d’un paquet avec des corrections dans ce paquet sont des exemples de changements sans rapport.
Suivez nos règles de formatage de code, éventuellement en lançant le script guix style pour le faire automatiquement (voir Formatage du code).
Si possible, utilisez des miroirs dans l’URL des sources (voir Invoquer guix download). Utilisez des URL stable, pas des URL générées. Par exemple, les archives GitHub ne sont pas nécessairement identiques d’une génération à la suivante, donc il vaut mieux dans ce cas cloner le dépôt. N’utilisez pas le champ name dans l’URL : ce n’est pas très utile et si le nom change, l’URL sera probablement erronée.
Vérifiez si Guix compile (voir Construire depuis Git) et corrigez les avertissements, surtout ceux à propos de symboles manquants.
Assurez-vous que vos changements ne cassent pas Guix et simulez un guix pull avec :
```
guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
```

Lorsque vous envoyez un correctif à la liste de diffusion, utilisez ‘[PATCH] …’ comme objet. Si votre correctif doit être appliqué à une autre branche que master, comme core-updates, spécifiez-le dans l’objet comme dans ‘[PATCH core-updates] …’.

You may use your email client, the git send-email command (voir Envoyer une série de correctifs) or the mumi send-email command (voir Interfaces utilisateurs à Debbugs). We prefer to get patches in plain text messages, either inline or as MIME attachments. You are advised to pay attention if your email client changes anything like line breaks or indentation which could potentially break the patches.

Attendez-vous à un délai entre le moment où vous envoyez votre tout premier correctif à guix-patches@gnu.org et le moment où le message sera reçu. Vous devez attendre de recevoir un message de confirmation avec le numéro de suivi assigné à votre correctif. Les confirmations suivantes ne seront pas retardées.

Lorsqu’un bogue est résolu, veuillez fermer le fil en envoyant un courriel à NUMÉRO_PROBLÈME-done@debbugs.gnu.org.