7 astuces pour rapporter les bogues Debian efficacement et voir vos problèmes résolus

Remplir des rapports de bogue constitue la façon la plus courante de contribuer pour les utilisateurs. Bien que cela ne soit pas très difficile, je vais vous donner quelques conseils pour améliorer la qualité de vos rapports. Après tout, lorsque vous prenez du temps pour rapporter un bogue, c’est dans l’espoir de le voir résolu… Alors voyons comment mettre le plus de chances de votre côté.

1. Essayez de reproduire le bug

Si vous ne pouvez pas reproduire le bogue, il sera alors impossible de trouver sa cause d’origine, et par conséquent de le résoudre. Dans ce cas, je vous suggère d’attendre jusqu’à ce que vous ayez rencontré ce bogue plusieurs fois. Vous trouverez peut-être ce qui le provoque (ou ce qui semble favoriser son apparition). Si l’application a un mode debug/verbose, ce serait une bonne idée de l’activer jusqu’à ce que le bug apparaisse une deuxième fois. Les logs générés seront très utiles au développeur pour comprendre ce qui s’est exactement passé.

Par conséquent, ne remplissez pas un rapport de bogue tout de suite, à moins que vous puissiez le reproduire. L’exception à la règle, c’est lorsque l’application donne quelques informations telles qu’un core-dump, une back-trace ou un message d’erreur.

Bien entendu, si le bogue apparaît lors d’une mise à jour, il est difficile de le reproduire (à moins de posséder plusieurs ordinateurs), mais vous devriez tout de même le rapporter. Assurez-vous d’y intégrer toutes les informations qui s’y rapportent (version des paquets avant et après la mise à jour logs de la mise à jour, etc).

2. Faîtes de votre mieux pour identifier le paquet mis en cause

Lorsque vous rapportez un bogue à Debian, vous devez l’assigner à un paquet. Bien qu’il existe des pseudo-paquets utiles pour les problèmes ne se rapportant pas directement à un véritable paquet, dans la plupart des cas vous devrez rapporter le bogue concernant le paquet particulier qui semble être la cause du problème rencontré.

De la même façon, vous devrez autant que possible attribuer le problème à un fichier (par exemple l’exécutable de l’application buggée). À partir du moment où vous connaissez le nom du fichier, vous pouvez utiliser dpkg -S pour identifier le paquet correspondant.

$ dpkg -S /usr/bin/hamster-time-tracker
hamster-applet: /usr/bin/hamster-time-tracker 

Notez que reportbug accepte pour paramètre un nom de fichier et fera la conversion ci-dessus à votre place.

Si vous ne connaissez que le nom de l’application (mais pas le nom du fichier de l’exécutable associé), vous pouvez utiliser dpkg -S avec un motif afin qu’il retourne tous les résultats correspondants :

$ dpkg -S hamster
hamster-applet: /usr/share/applications/hamster-applet.desktop
hamster-applet: /usr/share/gnome/help/hamster-applet/es/statistics.page
[…]
hamster-applet: /usr/bin/hamster-time-tracker
[…]

Ou vous pouvez aussi vérifier dans la liste des paquets installés :

$ dpkg -l "*hamster*"
Souhait=inconnU/Installé/suppRimé/Purgé/H=à garder
| État=Non/Installé/fichier-Config/dépaqUeté/échec-conFig/H=semi-installé/W=attend-traitement-déclenchements
|/ Err?=(aucune)/besoin Réinstallation (État,Err: majuscule=mauvais)
||/ Nom Version Architecture Description
+++-=========================-=================-=================-=======================================================
ii hamster-applet 2.91.3+git2012051 all time tracking applet for GNOME 

3. Vérifiez que le bogue n’est pas déjà signalé ou résolu

Si une nouvelle version du logiciel est disponible, c’est une bonne idée d’essayer de reproduire le problème aussi avec cette dernière version. Étant donné que les développeurs ont tendance à se préoccuper uniquement de la dernière version, ils essaieront de le reproduire dans cette version, et risquent d’être agacés si le bogue que vous rapportez est déjà résolu. C’est pourquoi les rapports de bogue des utilisateurs de testing/unstable ont tendance à être plus utile que les rapports des utilisateurs de la stable.

Dans tous les cas, vous devrez vérifier que le bogue n’a pas encore été rapporté : créer un doublon est inutile et génère seulement plus de travail pour le développeur qui doit fusionner les deux bogues.

Notez que reportbug vous montrera automatiquement la liste des bogues ouverts avant de vous permettre d’en soumettre un nouveau.

4. Utilisez reportbug

Bien que le système de rapport de bogue Debian permette à quiconque de soumettre un nouveau bug avec un simple mail, vous devriez vraiment utiliser un programme fait pour ça tel que reportbug (ou reportbug-ng) car il inclura automatiquement de nombreuses informations utiles dans le rapport généré (version des dépendances, architecture actuelle, etc.) et vous assistera à chaque étape.

5. Décrivez le problème afin que le développeur puisse le reproduire

Idéalement, votre rapport devrait inclure tout ce qui est nécessaire au développeur pour reproduire le problème sur son système. Si un quelconque document provoque le bogue, attachez-le au rapport.

Décrivez les étapes permettant de reproduire le bogue avec autant de détails que si vous vouliez l’expliquer à votre grand-mère. Expliquez le comportement attendu du programme, et ce qui s’est passé à la place.

Vous pouvez en apprendre bien plus sur la façon d’écrire un bon rapport de bug dans cet article : How to report bugs effectively. C’est un peu long mais ça en vaut la peine si vous envisagez de rapporter des bogues, et donc d’interagir avec les développeurs.

6. Soyez sympa et prêt à aider

Lorsque vous remplissez un rapport de bogue, gardez à l’esprit que vous êtes en train d’écrire à un développeur bénévole de logiciel libre, et non à un service consommateur. Vous devriez être respectueux et suivre les règles usuelles de courtoisie. Le temps disponible des développeurs est limité, et de devrait pas être gaspillé.

Soyez prêt à aider, car si un développeur commence à examiner votre problème, il peut avoir besoin d’informations supplémentaires (en particulier s’il ne peut le reproduire), et vous devriez être prêt à lui fournir. C’est pourquoi il est important de garder tout ce dont vous avez besoin pour reproduire le problème.

Dans certains cas, le mainteneur Debian peut être surchargé de travail. Vous pouvez offrir votre aide en transférant le bogue au traqueur de bogue amont.(Voir Upstream bug tracker) Ce sera toujours apprécié. Si vous êtes à peu près certain que le problème n’est pas spécifique à Debian, vous pouvez faire ça directement et définir l’URL du rapport de bug amont dans le champ « transféré » (par exemple avec bts forwarded <bogue> <url>).

7. Utilisez le niveau de gravité convenable

Le système de suivi de bug Debian vous permet de définir la gravité initiale du rapport de bug (en ordre décroissant de gravité : critical, grave, serious, important, normal, minor, wishlist). Choisissez la gravité convenable selon les définitions officielles et ne les interprétez pas de travers.

En particulier, n’exagérez pas la gravité : par exemple, si vous avez perdu des données à cause d’une mauvaise utilisation du logiciel, il ne s’agit pas d’une sévérité « critical » (i.e. "rm -rf *" n’est pas un bogue critique de rm). Si vous utilisez seulement une petite partie d’un logiciel, et que cette partie ne fonctionne pas, le paquet peut être inutilisable pour vous, mais pas pour tout le monde. Il ne s’agit donc pas d’une gravité « grave ». La gravité « important » est la plupart du temps un bon choix dans ce cas.

Ne sous-estimez pas non plus la gravité, si un problème est suffisamment important pour devoir être réparé avec la prochaine version stable (par exemple une régression par rapport à la version précédente), choisissez alors une gravité de niveau release-critical (i.e au moins « serious »). Le mainteneur et le gestionnaire de version peut toujours abaisser le niveau de gravité s’il n’est pas en accord avec votre jugement initial.

Et maintenant, lancez-vous à cœur joie dans la soumission de bogues ! Vous pouvez vous référer à cet article via cette URL raccourcie : https://raphaelhertzog.fr/go/bugreporting/

Ceci est une traduction sous licence CC-BY-SA 3.0 de mon article 7 tips de file useful Debian bug reports and get your problem solved contribuée par Xavier Cartron. Si vous avez apprécié cet article, cliquez ici pour découvrir comment m’encourager à en fournir d’autres.

Recommandations pour le parrainage de paquets Debian

Parrainer un paquet signifie l’uploader pour le compte d’une autre personne (qui se trouve être, la plupart du temps, un nouveau contributeur voulant devenir mainteneur de paquet). Le parrainage est réservé aux développeurs Debian, car ils sont réputés connaître les tenants et aboutissants de l’empaquetage. Cet article essaye ici de documenter ce processus, afin de s’assurer que le parrain effectue un travail satisfaisant, au regard des standards Debian.

Parrainer un paquet dans l’archive Debian n’est pas une tâche triviale. Cela suppose que vous ayez vérifié son empaquetage et jugé qu’il était du niveau de qualité attendu par Debian. Voyons voir ce que vous pouvez et devriez faire dans un tel cas :

Parrainer l’envoi initial

Parrainer un tout nouveau paquet requiert une analyse méthodique de son empaquetage : compiler le paquet et tester le logiciel proprement dit n’est absolument pas suffisant ! Vous devez ouvrir chaque fichier dans le répertoire debian à la recherche de problèmes potentiels. Voici une liste que vous pouvez utiliser pour réaliser cet audit :

  • Vérifier que l’archive TAR amont fournie est identique à celle distribuée par l’auteur amont (dans le cas où les sources ont été ré-empaquetées pour Debian, il vous faudra générer l’archive par vous-même) ;
  • Lancer lintian. Ce dernier remontera beaucoup de problèmes « habituels ». Vérifier que les overrides employés pour masquer des erreurs sont pleinement justifiés ;
  • Lancer licensecheck et vérifier que debian/copyright est correct et exhaustif. Rechercher les problèmes de licences (comme les fichiers dont l’en-tête comporte « All rights reserved », ou une licence non compatible avec les principes du logiciel libre selon Debian) ;
  • Compiler le paquet avec pbuilder (ou équivalent), afin de s’assurer que les dépendances de compilation soient complètes ;
  • Rechercher les erreurs dans debian/control : est-ce qu’il suit les bonnes pratiques ? Est-ce que la liste des dépendances est complète ?
  • Rechercher les erreurs dans debian/rules : est-ce qu’il suit les bonnes pratiques ? Est-il améliorable ?
  • Rechercher les erreurs dans les scripts de configuration (preinst, postinst, prerm, postrm, config) : est-ce que les scripts preinst et postrm fonctionneront si les dépendances ne sont pas installées ? Est-ce que tous les scripts sont bien idempotents (c’est à dire qu’ils peuvent être lancés un nombre arbitraire de fois sans conséquences fâcheuses) ?
  • Passer en revue toutes les modifications faites aux fichiers amont (soit dans les fichiers .diff.gz, soit dans debian/patches/ ou directement embarquées dans le tarball debian en ce qui concerne les fichiers binaires). Est-ce que ces modifications sont justifiées ? Sont-elles proprement documentées (en utilisant DEP-3 dans le cas des patchs) ?
  • Pour chaque fichier, il vous faut vous demander pourquoi il est là et s’il constitue la meilleure manière d’atteindre le but recherché. Est-ce que le mainteneur suit bien les bonnes pratiques de l’empaquetage décrites dans la Référence du Développeur Debian ?
  • Compiler, installer les paquets, et essayer les logiciels. Assurez-vous de pouvoir supprimer et purger les paquets. Vous pouvez aussi tester les paquets grâce à piuparts.

Si cet audit n’a révélé aucun problème, vous pouvez alors uploader le paquet. Mais souvenez-vous que même si vous n’en êtes pas le mainteneur, le parrain reste responsable de ce qu’il a envoyé dans l’archive Debian. C’est pourquoi vous êtes encouragé à suivre le paquet grâce au PTS (Package Tracking System – Système de Suivi des Paquets).

Parrainer la mise à jour d’un paquet déjà existant

Vous supposerez généralement que le paquet a déjà été l’objet d’un examen minutieux. Donc plutôt que de recommencer, vous analyserez avec beaucoup d’attention les différences entre l’ancienne et la nouvelle version préparée par le mainteneur. Si vous n’avez pas vous-même effectué la revue initiale, vous souhaiterez peut-être jeter un coup d’oeil un peu plus approfondi au paquet en lui-même, juste au cas où le premier « relecteur » ait été un peu négligeant.

Pour comparer, il vous faut les deux versions. Télécharger la version source actuelle (grâce à apt-get source) et recompiler-là (ou télécharger le fichier binaire correspondant : aptitude download). Télécharger ensuite le paquet source à parrainer (la plupart du temps via dget).

Lisez les nouvelles entrées du fichier de suivi des modifications (changelog) : il devrait vous dire à quoi vous attendre. L’outil principal que vous allez utiliser est debdiff, que vous pouvez lancer avec deux paquets sources (fichiers .dsc) ou deux fichiers binaires, ou encore deux fichiers .changes (il comparera alors tous les fichiers binaires listés dans les fichiers .changes).

Si vous comparez les paquets sources (en excluant les fichiers upstream dans le cas d’une nouvelle version upstream, par exemple en filtrant la sortie de debdiff grâce à filterdiff -i '*/debian/*'), vous devez comprendre toutes les modifications qui s’affichent, et elles doivent être proprement documentées dans le suivi des modifications Debian.

S’il n’y a rien à relever, compiler le paquet et comparer les fichiers binaires, afin de vérifier que les modifications vues dans les sources n’ont aucun effet de bord (comme des fichiers supprimés par erreurs, des dépendances manquantes, …).

Il peut également être utile de contrôler l’état du paquet sur le PTS, histoire de vérifier que le mainteneur n’a rien manqué d’important : peut-être que des traductions en attente auraient pu être intégrées, ou bien le paquet a fait l’objet d’une mise à jour indépendante (NMU – Non-Maintener Upload) mais le mainteneur a oublié d’en reprendre les modifications dans sa nouvelle version. Il se peut également qu’un bogue critique pour la publication ait été laissé de côté et bloque la migration vers testing… bref : quelle qu’en soit la nature, si vous trouvez quelque chose qui aurait pu être (mieux) fait, il est temps de le dire au mainteneur de sorte à ce qu’il puisse s’améliorer la prochaine fois, et qu’il ait plus justement conscience de ses responsabilités.

Si vous n’avez trouvé aucun problème, alors il est temps d’uploader la nouvelle version. Dans tous les autres cas, demandez au mainteneur de vous envoyer une version corrigée.


Cet article a servi de base à la rédaction de la section correspondante de la Référence du développeur Debian (cf #453313). Cliquez ici pour soutenir mon travail sur la documentation Debian.

Ceci est une traduction de mon article Best practices when sponsoring Debian packages contribuée par Weierstrass01.

4 astuces pour maintenir un paquet Debian « 3.0 (quilt) » dans un système de suivi de versions (VCS)

La plupart des paquets Debian sont gérés grâce à un logiciel de gestion de versions (VCS – Version Control System) tel que git, subversion, bazaar ou mercurial. Les particularités du format « 3.0 (quilt) » ne sont pas sans conséquences sur la gestion des paquets dans un VCS, et cet article va vous présenter quelques astuces afin d’en rendre l’usage plus agréable.

(Tous les exemples présentés ci-dessous s’appuient sur l’utilisation de git comme VCS).

1. Exclusion du répertoire .pc

Le répertoire .pc est utilisé par quilt afin de stocker ses données internes (liste des patchs appliqués, sauvegarde des fichiers modifiés). Il est également créé par dpkg-source de telle sorte que quilt « sache » que les patchs sont situés dans debian/patches (et non dans patches, qui est le répertoire que quilt utilise par défaut). À ce titre, le répertoire est conservé même lorsque plus aucun patch n’est actuellemement appliqué.

Vous ne tenez cependant pas à conserver ce répertoire dans votre dépôt : il doit donc être mentionné dans la liste des fichiers exclus. Avec git, il suffit d’indiquer :

$ echo ".pc" >>.gitignore
$ git add .gitignore
$ git commit -m "Ignore quilt dir"

Le fichier .gitignore n’étant pas pris en compte par dpkg-source, le paquet source généré par ce dernier ne sera pas « pollué ».

2. Retirer les patchs après la compilation

Si vous stockez vos sources « amont » avec les patchs non appliqués (ce que font la plupart des gens) et que vous ne compilez pas vos paquets dans un répertoire temporaire prévu à cet effet, alors vous souhaitez probablement « désappliquer » les patchs après la compilation, de sorte à retrouver un dépôt dans un état « propre ».

C’est désormais le comportement par défaut de dpkg-source. S’il a dû appliquer les patchs, il les enlèvera automatiquement également.

Mais on peut tout de même forcer ce comportement en ajoutant « unapply-patches » à debian/source/local-options :

$ echo "unapply-patches" >>debian/source/local-options
$ git add debian/source/local-options
$ git commit -m "Unapply patches after build"

svn-buildpackage compilant systématiquement dans un répertoire temporaire, le dépôt est laissé exactement dans le même état qu’avant la compilation : cette option est inutile dans ce cas. Ce comportement peut également être demandé à git-buildpackage grâce à l’option --git-export-dir=../build-area/ (../build-area/ étant le répertoire utilisé par svn-buildpackage, cette option force git-buildpackage à se comporter comme svn-buildpackage).

3. Gérer vos patchs quilt comme une branche git

Plutôt que de gérer les patchs spécifiques à Debian via quilt, il est possible d’utiliser git lui-même. Avec git-buildpackage vient l’outil gbp-pq (Git-BuildPackage Patch Queue – File des patchs de git-buildpackage). gbp-pq permet l’export d’une série quilt dans une branche git, que vous pouvez alors manipuler comme vous le souhaitez. Chaque commit représentant un patch, vous devez « rebaser » cette branche afin d’éditer les commits intermédiaires. Jetez un oeil à la documentation de gbp-pq pour appronfondir le sujet.

Alternative à gbp-pq, l’utilisation de git-dpm est plus compliquée, mais présente l’avantage de conserver l’historique de toutes les branches utilisées pour générer les séries quilt de toutes les publications Debian. Son principe de fonctionnement est très bien expliqué sur son site, et vous pouvez également souhaiter lire la revue qu’en a fait Sam Hartman, qui en présente les limites.

4. Documenter la manière de passer en revue les modifications

L’un des principaux bénéfices liés à l’utilisation du nouveau format source tient au fait qu’il est dorénavant simple de passer en revue les modifications amont : celles-ci sont conservées en autant de patchs distincts proprement documentés (et, idéalement, en utilisant le format DEP-3). En utilisant les outils décrits précédemment, le message de commit devient l’en-tête du patch. Il devient donc important de saisir des messages de commit explicites.

Cette méthode fonctionne bien tant que votre méthode de travail prend appui sur les patchs Debian, regroupés dans une branche que vous rebasez sur les sources amont à chaque publication. Certains mainteneurs n’aiment pas cette méthode de travail et préfèrent voir appliquer les modifications propres à Debian directement sur la branche d’empaquetage. Ils sautent alors vers une nouvelle version amont en la fusionnant dans cette dernière. Il est difficile dans ce cas de générer une série quilt à partir du système de suivi de versions. Il faut à la place indiquer à dpkg-source de stocker toutes les modifications dans un seul patch (qui devient alors équivalent au bon vieux .diff.gz), et documenter dans son en-tête comment mieux passer en revue les modifications, par exemple dans l’interface Web du VCS.

Le premier comportement est obtenu en passant l’option --single-debian-patch, et le second en écrivant l’en-tête dans debian/source/patch-header :

$ echo "single-debian-patch" >> debian/source/local-options
$ cat >debian/source/patch-header <<END
This patch contains all the Debian-specific
changes mixed together. To review them
separately, please inspect the VCS history
at http://git.debian.org/?=collab-maint/foo.git
<Put more details here>
END

Ceci est une traduction de mon article 4 tips to maintain a “3.0 (quilt)” Debian source package in a VCS contribuée par Weierstrass01. Vous voulez d’autres tutoriels comme celui-ci ? Cliquez ici pour vous abonner à ma newsletter et recevoir les nouveaux articles par email.

Ne créez pas votre paquet Debian avec dpkg -b

J’ai pu observer de nombreuses personnes, ces dernières années, essayant d’utiliser dpkg --build pour créer des paquets Debian. Et, de fait, si vous lisez les pages de manuel de dpkg et de dpkg-deb, l’option semble bien appropriée à cet usage :

-b, --build répertoire [archive|répertoire]

Crée une archive Debian avec l’arborescence contenue dans répertoire. répertoire doit posséder un sous-répertoire DEBIAN qui contient les fichiers de contrôle tel que le fichier « control » lui-même. Ce répertoire n’apparaît pas dans l’archive de l’arborescence du paquet binaire ; mais les fichiers qu’il contient sont mis dans la zone de contrôle du paquet binaire.

On peut en conclure que oui, effectivement, dpkg-deb est l’outil créant en dernière étape les fichiers .deb (aussi connus sous le nom de paquets binaires). Ce qui ne veut pas dire que vous êtes censé appeler un tel outil « bas-niveau » vous-même. En effet, si vous souhaitez empaqueter proprement un logiciel, vous devez plutôt créer un paquet source Debian, qui partira du code source amont pour créer des paquets binaires respectant la charte technique Debian.

Créer un tel paquet source implique également de préparer une arborescence de répertoires (mais avec un sous-répertoire « debian »), ce qui est probablement plus compliqué que d’appliquer dpkg -b à un répertoire ciselé « à la main ». Mais le résultat en est d’autant plus versatile : les outils utilisés apportent une valeur ajoutée en analysant/modifiant dynamiquement les fichiers à l’intérieur de votre paquet (par exemple, les dépendances envers les bibliothèques C requises par votre paquet sont insérées automatiquement).

Si cette méthodologie vous était inconnue, vous souhaiterez peut-être approfondir le sujet grâce au manuel du Nouveau Mainteneur ou à la Charte Debian.

Ceci est une traduction de mon article Avoid a newbie packager mistake: don’t build your Debian packages with dpkg -b contribuée par Weierstrass01.

Abonnez-vous à ce blog par RSS ou par email pour recevoir tous les prochains articles et améliorer votre maîtrise de Debian/Ubuntu.