Ubuntu logo

Packaging Guide

3. Correction d’un bogue dans Ubuntu

3.1. Introduction

Si vous avez suivi les instructions pour obtenir la configuration de Ubuntu Développement, vous devriez être configuré et prêt à commencer.

./_images/fixing-a-bug.png

Comme vous pouvez le constater dans l’image ci-dessus, il n’y a pas de surprises dans le processus de correction des bogues dans Ubuntu : vous découvrez un problème, vous obtenez le code, vous travaillez sur le correctif, le testez, soumettez vos modifications dans Launchpad et demandez à ce qu’elles soient examinées puis fusionnées. Dans ce guide, nous allons passer toutes les étapes nécessaires une par une.

3.2. Trouver le problème

Il existe de nombreuses façons de trouver des choses sur lesquelles travailler. Ce sera peut-être un rapport de bogue que vous-même pouvez rencontrer (ce qui vous donne une bonne occasion de tester le correctif), ou un problème relevé par ailleurs, éventuellement dans un rapport de bogue.

Take a look at the bitesize bugs in Launchpad, and that might give you an idea of something to work on. It might also interest you to look at the bugs triaged by the Ubuntu One Hundred Papercuts team.

3.3. Déterminer ce qu’il faut corriger

Si vous ne connaissez pas le paquet source contenant le code problématique, mais que vous connaissez le chemin du programme concerné sur votre système, vous pouvez découvrir sur quel paquet source vous pourrez travailler.

Let’s say you’ve found a bug in Bumprace, a racing game. The Bumprace application can be started by running /usr/bin/bumprace on the command line. To find the binary package containing this application, use this command:

$ apt-file find /usr/bin/bumprace

Cela affichera :

bumprace: /usr/bin/bumprace

Note that the part preceding the colon is the binary package name. It’s often the case that the source package and binary package will have different names. This is most common when a single source package is used to build multiple different binary packages. To find the source package for a particular binary package, type:

$ apt-cache showsrc bumprace | grep ^Package:
Package: bumprace
$ apt-cache showsrc tomboy | grep ^Package:
Package: tomboy

apt-cache fait partie de l’installation standard d’Ubuntu.

3.4. Confirmer le problème

Once you have figured out which package the problem is in, it’s time to confirm that the problem exists.

Supposons que le paquet bumprace n’a pas de page d’accueil dans sa description de paquet. Dans un premier temps, vous vérifiez si le problème n’est pas déjà résolu. C’est facile à vérifier, soit en jetant un coup d’œil à la Logithèque Ubuntu, soit en exécutant :

apt-cache show bumprace

La sortie devrait être similaire à ceci :

Package: bumprace
Priority: optional
Section: universe/games
Installed-Size: 136
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
XNBC-Original-Maintainer: Christian T. Steigies <cts@debian.org>
Architecture: amd64
Version: 1.5.4-1
Depends: bumprace-data, libc6 (>= 2.4), libsdl-image1.2 (>= 1.2.10),
         libsdl-mixer1.2, libsdl1.2debian (>= 1.2.10-1)
Filename: pool/universe/b/bumprace/bumprace_1.5.4-1_amd64.deb
Size: 38122
MD5sum: 48c943863b4207930d4a2228cedc4a5b
SHA1: 73bad0892be471bbc471c7a99d0b72f0d0a4babc
SHA256: 64ef9a45b75651f57dc76aff5b05dd7069db0c942b479c8ab09494e762ae69fc
Description-en: 1 or 2 players race through a multi-level maze
 In BumpRacer, 1 player or 2 players (team or competitive) choose among 4
 vehicles and race through a multi-level maze. The players must acquire
 bonuses and avoid traps and enemy fire in a race against the clock.
 For more info, see the homepage at http://www.linux-games.com/bumprace/
Description-md5: 3225199d614fba85ba2bc66d5578ff15
Bugs: https://bugs.launchpad.net/ubuntu/+filebug
Origin: Ubuntu

Un contre-exemple serait gedit, qui dispose d’une page d’accueil :

$ apt-cache show gedit | grep ^Homepage
Homepage: http://www.gnome.org/projects/gedit/

Parfois, vous constaterez qu’un problème particulier sur lequel vous vous penchez est déjà corrigé. Pour éviter le gaspillage des efforts et le travail en doublon, il est logique de commencer par un petit travail de détective.

3.5. Localisation de bogue

En premier lieu, nous devons vérifier l’existence préalable d’un bogue pour ce problème dans Ubuntu. Peut-être que quelqu’un travaille déjà sur un correctif, ou nous pouvons contribuer à la solution d’une manière ou d’une autre. Pour Ubuntu, nous jetons un coup d’œil à https://bugs.launchpad.net/ubuntu/+source/bumprace et constatons qu’aucun bogue n’y est ouvert avec notre problème.

Note

Pour Ubuntu, l’URL https://bugs.launchpad.net/ubuntu/+source/<paquet> devrait toujours afficher la page concernant les bogues du paquet source en question.

Pour Debian, qui est la principale source des paquets d’Ubuntu, nous jetons un œil sur http://bugs.debian.org/src:bumprace et nous ne pouvons de nouveau pas trouver de rapport de bogue pour notre problème.

Note

Pour Debian, l’URL http://bugs.debian.org/src:<paquet> devrait toujours afficher la page concernant les bogues du paquet source en question.

Le problème sur lequel nous travaillons est spécifique, car il concerne uniquement les bits d’empaquetage liés à bumprace. Si le problème se trouvait dans le code source, il serait utile de vérifier également le traceur de bogues en amont. Malheureusement, il arrive souvent que cela soit différent à chaque paquet examiné ; mais si vous effectuez une recherche sur internet, vous devriez le trouver facilement dans la plupart des cas.

3.6. Offrir de l’aide

Si vous avez trouvé un bogue ouvert, qu’il n’est affecté à personne et que vous êtes en mesure de régler le problème, vous pouvez le commenter avec votre solution. N’oubliez pas d’inclure autant d’informations que possible : dans quelles circonstances se produit le bogue ? Comment avez-vous résolu le problème ? Avez-vous testé votre solution ?

Si aucun rapport de bogue n’a été déposé, vous pouvez en déposer un. Une chose que vous devriez garder à l’esprit est : Le problème est-il si petit qu’une simple demande de réalisation serait suffisante ? Avez-vous réussi à partiellement résoudre le problème et vous voulez au moins partager votre partie de la solution ?

C’est très bien si vous pouvez offrir votre aide, et elle sera assurément appréciée.

3.7. Obtenir le code

Once you know the source package to work on, you will want to get a copy of the code on your system, so that you can debug it. The ubuntu-dev-tools package has a tool called pull-lp-source that a developer can use to grab the source code for any package. For example, to grab the source code for the tomboy package in xenial, you can type this:

$ pull-lp-source bumprace xenial

If you do not specify a release such as xenial, it will automatically get the package from the development version.

Once you’ve got a local clone of the source package, you can investigate the bug, create a fix, generate a debdiff, and attach your debdiff to a bug report for other developers to review. We’ll describe specifics in the next sections.

3.8. Travailler sur un correctif

Il existe des livres entiers sur la façon de trouver des bogues, de les corriger, de les tester, etc. Si vous êtes complètement novice en programmation, essayez en premier lieu de corriger les bogues simples comme les fautes de frappe évidentes. Essayez de minimiser les changements autant que possible et documentez clairement vos modifications et hypothèses.

Avant de travailler sur un correctif vous-même, assurez-vous de vérifier que personne d’autre ne l’a déjà corrigé ou est en train de le faire. Les bonnes sources à vérifier sont :

  • Traceur de bogues en amont (et dans Debian) (bogues ouverts et fermés),

  • Historique des révisions en amont (ou version plus récente) pourrait avoir résolu le problème,

  • des bogues ou des ajouts de paquets de distributions Debian ou autres.

You may want to create a patch which includes the fix. The command edit-patch is a simple way to add a patch to a package. Run:

$ edit-patch 99-new-patch

Cela va copier l’empaquetage dans un répertoire temporaire. Vous pouvez maintenant éditer les fichiers avec un éditeur de texte ou appliquer des correctifs en amont, par exemple:

$ patch -p1 < ../bugfix.patch

Après avoir modifié le fichier, saisissez exit ou appuyez sur ctrl-d pour quitter l’environnement temporaire. Le nouveau correctif a été ajouté dans debian/patches.

You must then add a header to your patch containing meta information so that other developers can know the purpose of the patch and where it came from. To get the template header that you can edit to reflect what the patch does, type this:

$ quilt header --dep3 -e

This will open the template in a text editor. Follow the template and make sure to be thorough so you get all the details necessary to describe the patch.

In this specific case, if you just want to edit debian/control, you do not need a patch. Put Homepage: http://www.linux-games.com/bumprace/ at the end of the first section and the bug should be fixed.

3.8.1. Documenter le correctif

Il est très important de documenter abondamment vos modifications afin que les développeurs qui reliront votre code dans le futur n’aient pas à deviner ce qu’étaient votre raisonnement et vos hypothèses. Chaque paquet source Debian et Ubuntu inclut debian/changelog, où les modifications de chaque paquet téléchargé sont suivies.

Le moyen le plus simple de mettre à jour est d’exécuter :

$ dch -i

Cela vous ajoute une entrée passe-partout du changelog et lance un éditeur dans lequel vous pourrez remplir les blancs. Un exemple de ceci pourrait être :

specialpackage (1.2-3ubuntu4) trusty; urgency=low

  * debian/control: updated description to include frobnicator (LP: #123456)

 -- Emma Adams <emma.adams@isp.com>  Sat, 17 Jul 2010 02:53:39 +0200

dch doit déjà remplir pour vous la première et la dernière ligne d’une telle entrée du changelog. La ligne 1 se compose du nom du paquet source, du numéro de version, de la version d’Ubuntu vers laquelle le paquet est transféré, du niveau d’urgence (qui est presque toujours «{nbsp]faible »). La dernière ligne contient toujours le nom, l’adresse électronique et l’horodatage du changement (au format RFC 5322).

Ces préoccupations en moins, concentrons-nous sur l’entrée effective du changelog elle-même : il est très important de renseigner :

  1. Where the change was done.
  2. What was changed.
  3. Where the discussion of the change happened.

Dans notre (très rare) exemple, le dernier point est couvert par (LP: #123456) se référant au bogue Launchpad 123456. Les rapports de bogues ou des fils de listes de diffusion ou les spécifications sont généralement de bonnes informations à fournir comme justification d’un changement. En prime, si vous utilisez la notation LP: #<numéro> pour les bogues sur Launchpad, le bogue sera automatiquement fermé quand le paquet correctif sera téléchargé vers Ubuntu.

In order to get it sponsored in the next section, you need to file a bug report in Launchpad (if there isn’t one already, if there is, use that) and explain why your fix should be included in Ubuntu. For example, for tomboy, you would file a bug here (edit the URL to reflect the package you have a fix for). Once a bug is filed explaining your changes, put that bug number in the changelog.

3.9. Tester le correctif

Pour construire un paquet de test avec vos modifications, exécutez ces commandes:

$ debuild -S -d -us -uc
$ pbuilder-dist <release> build ../<package>_<version>.dsc

This will create a source package from the branch contents (-us -uc will just omit the step to sign the source package and -d will skip the step where it checks for build dependencies, pbuilder will take care of that) and pbuilder-dist will build the package from source for whatever release you choose.

Note

If debuild errors out with “Version number suggests Ubuntu changes, but Maintainer: does not have Ubuntu address” then run the update-maintainer command (from ubuntu-dev-tools) and it will automatically fix this for you. This happens because in Ubuntu, all Ubuntu Developers are responsible for all Ubuntu packages, while in Debian, packages have maintainers.

In this case with bumprace, run this to view the package information:

$ dpkg -I ~/pbuilder/*_result/bumprace_*.deb

As expected, there should now be a Homepage: field.

Note

Dans de nombreux cas vous devrez réellement installer le paquet pour vous assurer qu’il fonctionne comme prévu. Notre cas est largement plus simple. Si la construction réussit, vous trouverez les paquets binaires dans ~/pbuilder/<release>_result. Installez-les à l’aide de la commande sudo dpkg -i <package>.deb ou en double-cliquant dessus dans votre gestionnaire de fichiers.

3.10. Submitting the fix and getting it included

With the changelog entry written and saved, run debuild one more time:

$ debuild -S -d

and this time it will be signed and you are now ready to get your diff to submit to get sponsored.

In a lot of cases, Debian would probably like to have the patch as well (doing this is best practice to make sure a wider audience gets the fix). So, you should submit the patch to Debian, and you can do that by simply running this:

$ submittodebian

Cela vous mènera à travers une série de mesures pour vous assurer que le bogue se retrouve au bon endroit. Assurez-vous de contrôler de nouveau la différence pour être certain qu’elle ne comprenne aucune modification antérieure non désirée.

La communication est importante, lorsque vous ajoutez une description à votre demande d’inclusion, soyez gentil de bien l’expliquer.

Si tout s’est bien déroulé, vous obtenez un message du système de suivi des bogues Debian avec plus d’informations. Cela peut parfois prendre quelques minutes.

It might be beneficial to just get it included in Debian and have it flow down to Ubuntu, in which case you would not follow the below process. But, sometimes in the case of security updates and updates for stable releases, the fix is already in Debian (or ignored for some reason) and you would follow the below process. If you are doing such updates, please read our Security and stable release updates article. Other cases where it is acceptable to wait to submit patches to Debian are Ubuntu-only packages not building correctly, or Ubuntu-specific problems in general.

But if you’re going to submit your fix to Ubuntu, now it’s time to generate a “debdiff”, which shows the difference between two Debian packages. The name of the command used to generate one is also debdiff. It is part of the devscripts package. See man debdiff for all the details. To compare two source packages, pass the two dsc files as arguments:

$ debdiff <package_name>_1.0-1.dsc <package_name>_1.0-1ubuntu1.dsc

In this case, debdiff the dsc you downloaded with pull-lp-source and the new dsc file you generated. This will generate a patch that your sponsor can then apply locally (by using patch -p1 < /path/to/debdiff). In this case, pipe the output of the debdiff command to a file that you can then attach to the bug report:

$ debdiff <package_name>_1.0-1.dsc <package_name>_1.0-1ubuntu1.dsc > 1-1.0-1ubuntu1.debdiff

The format shown in 1-1.0-1ubuntu1.debdiff shows:

  1. 1- tells the sponsor that this is the first revision of your patch. Nobody is perfect, and sometimes follow-up patches need to be provided. This makes sure that if your patch needs work, that you can keep a consistent naming scheme.
  2. 1.0-1ubuntu1 shows the new version being used. This makes it easy to see what the new version is.
  3. .debdiff is an extension that makes it clear that it is a debdiff.

While this format is optional, it works well and you can use this.

Next, go to the bug report, make sure you are logged into Launchpad, and click “Add attachment or patch” under where you would add a new comment. Attach the debdiff, and leave a comment telling your sponsor how this patch can be applied and the testing you have done. An example comment can be:

This is a debdiff for Artful applicable to 1.0-1. I built this in pbuilder
and it builds successfully, and I installed it, the patch works as intended.

Make sure you mark it as a patch (the Ubuntu Sponsors team will automatically be subscribed) and that you are subscribed to the bug report. You will then receive a review anywhere between several housr from submitting the patch to several weeks. If it takes longer than that, please join #ubuntu-motu on freenode and mention it there. Stick around until you get an answer from someone, and they can guide you as to what to do next.

Once you have received a review, your patch was either uploaded, your patch needs work, or is rejected for some other reason (possibly the fix is not fit for Ubuntu or should go to Debian instead). If your patch needs work, follow the same steps and submit a follow-up patch on the bug report, otherwise submit to Debian as shown above.

Remember: good places to ask your questions are ubuntu-motu@lists.ubuntu.com and #ubuntu-motu on freenode. You will easily find a lot of new friends and people with the same passion that you have: making the world a better place by making better Open Source software.

3.11. Considérations supplémentaires

Si vous trouvez qu’il y a un certain nombre de choses triviales possibles à corriger en même temps dans un paquet, faites-le. Cela permettra d’accélérer l’examen et l’inclusion.

S’il y a plusieurs choses importantes que vous souhaitez corriger, il pourrait être plus judicieux d’envoyer des correctifs individuels ou de fusionner des propositions. S’il y a déjà des bogues individuels déposés sur le sujet, cela rend la chose encore plus aisée.