If you followed the instructions to get set up with Ubuntu Development, you should be all set and ready to go. As you can see in the image shiwn right, there are no surprises in the process of fixing bugs in Ubuntu: you found a problem, you get the code, work on the fix, test it, push your changes to Launchpad, and ask for it to be reviewed and merged. In this guide we will go through all the necessary steps one-by-one. Finding the problem There are a lot of different ways to find things to work on. It might be a bug report you are encountering yourself (which gives you a good opportunity to test the fix), or a problem you noted elsewhere, maybe in a bug report. Harvest is where we keep track of various TODO lists regarding Ubuntu development. It lists bugs that were fixed upstream or in Debian already, lists small bugs (we call them ‘bitesize’), and so on. Check it out and find your first bug to work on.
Si vous avez suivi les instructions pour vous préparer au développement d'Ubuntu, vous devriez être prêt à démarrer.
Comme vous pouvez le voir dans l'image de droite, il n'y a pas de surprises dans le processus de correction des bugs dans Ubuntu : vous avez trouvé un problème, vous récupérez le code, travaillez sur le correctif, le testez, téléchargez vos modifications sur Launchpad et demandez que votre travail soit examiné et fusionné. Dans ce guide, nous allons passer par toutes les étapes nécessaires une par une.
Trouver le problème
Il y a beaucoup de façons différentes de trouver des choses sur lesquelles travailler. Ça peut être un rapport de bogue que vous déposez vous-même (ce qui vous donne une bonne occasion de tester le correctif) ou un problème que vous avez trouvé ailleurs, peut-être dans un rapport de bogue.
Harvest [Ndt : la récolte] est l'endroit où nous gardons la trace de différentes listes de choses à faire concernant le développement d'Ubuntu. Cela répertorie les bogues déjà corrigés en amont ou dans Debian, cela liste de petits bogues (nous les appelons « Bitesize » [Ndt : « de la taille d'un octet »]), et ainsi de suite. Jetez-y un coup d’œil et trouvez votre premier bogue sur lequel travailler.
Figuring out what to fix If you don’t know the source package containing the code that has the problem, but you do know the path to the affected program on your system, you can discover the source package that you’ll need to work on. Let’s say you’ve found a bug in Tomboy, a note taking desktop application. The Tomboy application can be started by running /usr/bin/tomboy on the command line. To find the binary package containing this application, use this command: apt-file find /usr/bin/tomboy This would print out: tomboy: /usr/bin/tomboy
Comprendre ce qu'il y a à réparer
Si vous ne connaissez pas le paquet source contenant le code où se situe le problème, mais que vous connaissez le chemin du programme affecté sur votre système, vous pouvez découvrir le paquet source sur lequel vous aurez besoin de travailler.
Disons que vous avez trouvé un bug dans Tomboy, une application de bureau de prise de notes. L'application Tomboy peut être démarré en exécutant /usr/bin/tomboy sur la ligne de commande. Pour trouver le paquet binaire contenant cette application, utilisez cette commande :
apt-file find /usr/bin/tomboy
Cela devrait afficher :
tomboy: /usr/bin/tomboy
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 show tomboy | grep ^Source: In this case, nothing is printed, meaning that tomboy is also the name of the binary package. An example where the source and binary package names differ is python-vigra. While that is the binary package name, the source package is actually libvigraimpex and can be found with this command (and its output): apt-cache show python-vigra | grep ^Source: Source: libvigraimpex
Remarquez que la partie précédant les deux-points est le nom du paquet binaire. Il arrive souvent que le paquet source et le paquet binaire aient des noms différents. C'est notamment le cas quand un paquet source unique est utilisé pour construire plusieurs paquets binaires différents. Pour trouver le paquet source correspondant à un paquet binaire spécifique, saisissez :
apt-cache show tomboy | grep ^Source:
Dans ce cas, rien n'est affiché, ce qui signifie que Tomboy est aussi le nom du paquet binaire. Un exemple où les noms des paquets source et binaire sont différents est python-vigra. Ceci est le nom du paquet binaire, mais le paquet source s'appelle réellement libvigraimpex et peut être trouvé avec cette commande (et sa sortie) :
apt-cache show python-vigra | grep ^Source: Source: libvigraimpex
Getting the 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. This is done by *branching* the source package branch corresponding to the source package. Launchpad maintains source package branches for all the packages in Ubuntu. Once you’ve got a local branch of the source package, you can investigate the bug, create a fix, and upload your proposed fix to Launchpad, in the form of a Bazaar branch. When you are happy with your fix, you can submit a *merge proposal*, which asks other Ubuntu developers to review and approve your change. If they agree with your changes, an Ubuntu developer will upload the new version of the package to Ubuntu so that everyone gets the benefit of your excellent fix - and you get a little bit of credit. You’re now on your way to becoming an Ubuntu developer! We’ll describe specifics on how to branch the code, push your fix, and request a review in the following sections.
Récupérer le code
Une fois que vous connaîtrez le paquet source sur lequel travailler, vous souhaiterez avoir une copie du code sur votre système, de sorte que vous puissiez le déboguer. Cela se fait en « connectant » la branche des paquets sources correspondant au paquet source qui vous intéresse. Launchpad maintient des branches de paquets sources pour tous les paquets dans Ubuntu. Une fois que vous avez une branche locale du paquet source, vous pouvez étudier le bogue, créer un correctif et télécharger le correctif proposé sur Launchpad, sous la forme d'une branche Bazaar. Lorsque vous êtes satisfait de votre correction, vous pouvez soumettre une « proposition de fusion », qui demande à d'autres développeurs Ubuntu d'examiner et d'approuver votre changement. S'ils sont d'accord avec vos modifications, un développeur Ubuntu va télécharger la nouvelle version du paquet vers Ubuntu afin que chacun obtienne le bénéfice de votre excellente correction - et que vous obteniez un peu de remerciements. Vous êtes maintenant sur la bonne voie pour devenir un développeur Ubuntu ! Dans les sections suivantes, nous allons décrire les détails sur la manière de « brancher » du code, de pousser [Ndt : ou télécharger] votre correction et de demander une révision.
Work on a fix There are entire books written about finding bugs, fixing them, testing them, etc. If you are completely new to programming, try to fix easy bugs such as obvious typos first. Try to keep changes as minimal as possible and document your change and assumptions clearly. Before working on a fix yourself, make sure to investigate if nobody else has fixed it already or is currently working on a fix. Good sources to check are: • Upstream (and Debian) bug tracker (open and closed bugs), • Upstream revision history (or newer release) might have fixed the problem, • bugs or package uploads of Debian or other distributions.
Travailler sur un correctif
Il y a des livres entiers concernant la façon de trouver des bogues, les corriger, les tester, etc. Si vous êtes complètement nouveau en programmation, essayer d'abord de corriger des bogues faciles tels que les fautes de frappe évidentes. Essayez de faire des changements aussi minimes que possible et de documenter vos modifications et vos hypothèses clairement.
Avant de travailler sur un correctif vous-même, assurez-vous d'enquêter pour savoir si quelqu'un d'autre l'a déjà corrigé ou travaille actuellement sur un correctif. De bonnes sources à vérifier sont :
• les listes de bogues (ouverts et fermés) en amont (et sur Debian),
• l'historique de révisions en amont (ou sur une version nouvelle) pourrait avoir résolu le problème,
• des ajouts de paquets ou des bogues de Debian ou d'autres distributions.
If you find a patch to fix the problem, say, attached to a bug report, running this command in the source directory should apply the patch: patch -p1 < ../bugfix.patch Refer to the patch(1) manpage for options and arguments such as –dry-run, -p<num>, etc. Testing the fix To build a test package with your changes, run these commands: bzr bd – -S -us -uc pbuilder-dist <release> build ../<package>_<version>.dsc
Si vous trouvez un patch pour corriger le problème, disons attaché à un rapport de bogue, exécutez cette commande dans le répertoire source pour appliquer le patch :
patch -p1 < ../bugfix.patch
Reportez-vous à la page 1 du manuel de patch pour les options et les arguments tels que –dry-run, -p<num>, etc.
Tester la correction
Pour construire un paquet de test avec vos modifications, exécutez ces commandes :
bzr bd -- -S -us -uc pbuilder-dist <release> build ../<paquet>_<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 pbuilder-dist will build the package from source for whatever release you choose. Once the build succeeds, install the package from ~/pbuilder/<release>_result/ (using sudo dpkg -i <package>_<version>.deb). Then test to see if the bug is fixed. Documenting the fix It is very important to document your change sufficiently so developers who look at the code in the future won’t have to guess what your reasoning was and what your assumptions were. Every Debian and Ubuntu package source includes debian/changelog, where changes of each uploaded package are tracked. The easiest way to update this is to run: dch -i
Cela va créer un paquet source à partir du contenu de la branche (-us -uc va simplement supprimer l'étape qui signe le paquet source) et pbuilder-dist va construire le paquet depuis la source pour n'importe quelle version (« release ») que vous choisissez.
Une fois la génération réussie, installez le paquet depuis ~/pbuilder/<release>_result/ (en utilisant sudo dpkg -i <paquet>_<version>.deb). Puis testez pour voir si le bogue est corrigé.
Documenter le correctif
Il est très important de documenter suffisamment vos modifications pour que les développeurs qui regarderont le code à l'avenir n'aient pas à deviner quel avait été votre raisonnement et vos hypothèses. Chaque paquet source Debian et Ubuntu inclut un fichier debian/changelog, où les changements de chaque paquet téléchargé sont suivis.
La meilleure façon de mettre cela à jour est d'exécuter :
dch -i
This will add a boilerplate changelog entry for you and launch an editor where you can fill in the blanks. An example of this could be: specialpackage (1.2-3ubuntu4) natty; 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 should fill out the first and last line of such a changelog entry for you already. Line 1 consists of the source package name, the version number, which Ubuntu release it is uploaded to, the urgency (which almost always is ‘low’). The last line always contains the name, email address and timestamp (in RFC 5322 format) of the change.
Cela va ajouter une entrée passe-partout au fichier changelog pour vous et va lancer un éditeur où vous pourrez remplir les blancs. Un exemple de cela pourrait être :
paquetspecial (1.2-3ubuntu4) natty; urgence=low * debian/control: description actualisée pour inclure frobnicator (LP: #123456) -- Emma Adams <emma.adams@isp.com> Sat, 17 Jul 2010 02:53:39 +0200
dch devrait déjà avoir rempli la première et la dernière ligne d'une telle entrée du changelog pour vous. La ligne 1 se compose du nom du paquet source, du numéro de version, la version d'Ubuntu dans laquelle il sera téléchargé, l'urgence (qui est presque toujours « low » [Ndt : « faible »]. La dernière ligne contient toujours le nom, l'adresse électronique et l'horodatage (au format RFC 5322) de la modification.
With that out of the way, let’s focus on the actual changelog entry itself: it is very important to document: • where the change was done • what was changed • where the discussion of the change happened In our (very sparse) example, the last point is covered by (LP: #123456) which refers to Launchpad bug 123456. Bug reports or mailing list threads or specifications are usually good information to provide as a rationale for a change. As a bonus, if you use the LP: #<number> notation for Launchpad bugs, the bug will be automatically closed when the package is uploaded to Ubuntu.
Ceci étant dit, concentrons-nous sur l'entrée effective du changelog elle-même : il est très important de documenter :
• où le changement a été fait ;
• ce qui a changé ;
• où la discussion sur le changement a eu lieu.
Dans notre exemple (très simple), le dernier point est couvert par (LP: #123456) qui se réfère à Launchpad, bogue n° 123456. Les rapports de bogues ou les fils de discussion ou les spécifications sont généralement de bonnes informations à fournir comme justification pour un changement. En prime, si vous utilisez la notation LP: #<nombre> pour les bogues de Launchpad, le bogue sera automatiquement fermé quand le paquet sera téléchargé vers Ubuntu.
Committing the fix With the changelog entry written and saved, you can just run: debcommit and the change will be committed (locally) with your changelog entry as a commit message. To push it to Launchpad, as the remote branch name, you need to stick to the following nomenclature: lp:~<yourlpid>/ubuntu/<release>/<package>/<branchname> This could, for example, be lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456
Pousser le correctif
Une fois l'entrée du changelog écrite et enregistrée, il vous suffit d'utiliser :
debcommit
et le changement sera « commité » [Ndt : enregistré] localement avec votre entrée changelog utilisée comme message de « commit ».
Pour le pousser sur Launchpad, en tant que nom de la branche à distance, vous devez vous conformer à la nomenclature suivante :
lp:~<votreIDLaunchpad>/ubuntu/<release>/<package>/<branchname>
Cela pourrait, par exemple, être
lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456**
So, if you just run bzr push lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456 bzr lp-open you should be all set. The push command should push it to Launchpad, and the second command will open the Launchpad page of the remote branch in your browser. There, find the “(+) Propose for merging” link, and click it to get the change reviewed by somebody and included in Ubuntu. Next month: an overview of the Debian directory structure.
Donc, si vous exécutez simplement
bzr push lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456 bzr lp-open
vous devriez en avoir terminé. La commande push devrait le pousser sur Launchpad et la seconde commande ouvrira la page Launchpad de la branche à distance dans votre navigateur. Sur cette page, cherchez le lien « (+) Proposer pour la fusion », puis cliquez dessus pour que votre changement soit vérifié par quelqu'un et inclus dans Ubuntu.
Le mois prochain : un aperçu de la structure de répertoires Debian.