                   Ecrire des rapports de bogue pour FreeBSD

  Dag-Erling Smo/rgrav

   Contributed by  
   Version: 8def749c53
   2013-11-13 07:52:45 +0000 par Hiroki Sato.
   Resume

   Cet article decrit comment formuler et soumettre au mieux un rapport de
   bogue au projet FreeBSD.

   Version franc,aise de Marc Fonvieille <blackend@FreeBSD.org>.

   [ Multiples pages HTML / Page HTML unique ]

     ----------------------------------------------------------------------

   Table des matieres

   1. Introduction

   2. Quand soumettre un rapport de bogue

   3. Preparations

   4. Ecrire le rapport de bogue

   5. Suivi

   6. Lecture supplementaire

   Index

1. Introduction

   Une des experiences la plus frustrante que peut vivre un utilisateur de
   logiciel est de soumettre un rapport de bogue et de le voir etre ferme
   sommairement avec une explication laconique et sans aide du type "ce n'est
   pas un bogue" ou "PR bogue". De meme une des experiences la plus
   frustrante pour un programmeur est d'etre submerge de rapports de bogue
   qui ne sont pas vraiment des rapports de bogue mais plutot des demandes
   d'aide, ou qui contiennent peu ou pas d'information au sujet du probleme
   et sur comment le reproduire.

   Ce document essaye de decrire comment ecrire de bons rapports de bogue.
   Qu'est-ce qu'un bon rapport de bogue, allez-vous demander? Bien, pour
   aller directement au but, un bon rapport de bogue est celui qui peut etre
   analyse et traite rapidement, pour la satisfaction mutuelle de
   l'utilisateur et du developpeur.

   Bien que l'objectif principal de cet article soit les rapports de bogue
   pour FreeBSD, sa majeure partie devrait s'appliquer relativement bien `a
   d'autres projets de logiciels.

   Notez que cet article est organise thematiquement, et non pas de fac,on
   chronologique, ainsi vous devriez lire entierement ce document avant de
   soumettre un rapport de bogue, plutot que de le traiter comme un guide
   pas-`a-pas.

2. Quand soumettre un rapport de bogue

   Il existe beaucoup de types de problemes, et tous ne devraient pas etre `a
   l'origine d'un rapport de bogue. Naturellement, personne n'est parfait, et
   il y aura des moments ou vous serez convaincus d'avoir trouve un bogue
   dans un programme alors qu'en fait vous avez mal compris la syntaxe d'une
   commande ou fait une erreur dans un fichier de configuration (cependant
   cela peut en soi etre significatif d'une documentation sommaire ou d'une
   mauvaise gestion des erreurs dans l'application). Il reste beaucoup de cas
   ou la soumission d'un rapport de bogue n'est clairement pas la bonne ligne
   de conduite, et ne servira qu'`a frustrer les developpeurs et vous-meme.
   Reciproquement, il y a des cas ou il peut etre approprie de soumettre un
   rapport de bogue `a propos de quelque chose d'autre qu'un bogue-une
   amelioration ou une demande de fonctionnalite, par exemple.

   Aussi comment determiner ce qui est un bogue et ce qui ne l'est pas? Un
   principe de base simple est que votre probleme n'est pas un bogue s'il
   peut etre exprime sous la forme d'une question (habituellement de la forme
   "Comment puis-je faire X?" ou "Ou puis-je trouver Y?"). Ce n'est pas
   toujours aussi simple que cela, mais la regle de la question couvre une
   majorite de cas.

   Les quelques cas ou il peut etre approprie de soumettre un rapport de
   bogue au sujet de quelque chose qui n'est pas un bogue sont:

     * demandes d'amelioration de caracteristiques. C'est generalement une
       bonne idee de discuter de cela sur les listes de diffusion avant de
       soumettre un rapport de bogue.

     * Avis de mise `a jour de logiciels maintenus `a l'exterieur
       (principalement des logiciels portes, mais egalement des composants du
       systeme de base maintenus `a l'exterieur comme BIND ou divers
       utilitaires GNU).

   Une autre chose est que si le systeme sur lequel vous experimentez le
   bogue n'est pas suffisamment `a jour, vous devriez considerer serieusement
   de mettre `a jour et d'essayer de reproduire le probleme sur un systeme `a
   jour avant de soumettre le rapport de bogue. Il y peu de choses qui
   ennuieront plus un developpeur que de recevoir un rapport de bogue au
   sujet d'un probleme dej`a corrige.

   Et finalement, un bogue qui ne peut etre reproduit peut rarement etre
   corrige. Si le bogue se produit une seule fois et que vous ne pouvez pas
   le reproduire, et qu'il ne semble pas faire une autre victime, il y des
   chances qu'aucun des developpeurs ne sera en mesure de le reproduire ou de
   comprendre ce qui ne va pas. Cela ne signifie pas que rien ne s'est
   produit, mais plutot que les chances que votre rapport de bogue mene `a un
   correctif sont tres minces, et que vous devriez envisager de laisser
   tomber.

3. Preparations

   Une bonne regle `a suivre est de toujours effectuer une recherche avant de
   soumettre un rapport de bogue. Peut-etre que votre probleme a dej`a ete
   signale; peut-etre meme qu'on en discute actuellement sur les listes de
   diffusion, ou l'etait recemment; il se peut qu'il soit meme dej`a corrige
   dans une nouvelle version de ce que vous utilisez. Vous devriez donc
   verifier tous les lieux d'information avant de soumettre votre rapport de
   bogue. Pour FreeBSD, cela signifie:

     * La FAQ.

     * Les listes de diffusion-si vous n'etes pas inscrit, utilisez l'outil
       de recherche des archives sur le site de FreeBSD. Si votre probleme
       n'a pas ete aborde sur les listes, vous pourriez essayer de poster un
       message `a ce sujet et attendre quelques jours pour voir si quelqu'un
       peut deceler quelque chose que vous n'avez pas remarque.

     * Eventuellement, l'integralite du web-utilisez votre moteur de
       recherche favoris pour chercher toutes les references `a votre
       probleme. Vous pouvez meme obtenir des resultats des archives des
       listes de diffusion ou des forums de discussion que vous ne
       connaissiez pas ou parmi lesquels vous n'aviez pas pense chercher.

     * Et finalement, la base de donnees des PRs. A moins que votre probleme
       ne soit recent ou obscure, il y a assez de chance pour qu'il soit
       dej`a signale.

   Ensuite, vous devez etre sur que le rapport de bogue est envoye aux bonnes
   personnes.

   Le premier point ici est que si un probleme est un bogue dans un logiciel
   tiers (un logiciel porte ou pre-compile que vous avez installe), vous
   devrez rapporter le bogue `a l'auteur originel, et pas au projet FreeBSD.
   Il y a deux exceptions `a cette regle: la premiere est que si le bogue
   n'apparait pas sur d'autres plate-formes, dans quel cas le probleme peut
   venir de la fac,on dont le logiciel a ete porte sous FreeBSD; la seconde
   est si l'auteur original a dej`a corrige le probleme et sorti un correctif
   ou une nouvelle version de son logiciel, et que le logiciel porte de
   FreeBSD n'a pas encore ete mis `a jour.

   Le second point est que le systeme de suivi des bogues de FreeBSD classe
   les rapports de bogue en fonction de la categorie que l'auteur a choisie.
   Donc, si vous choisissez la mauvaise categorie, il y a de fortes chances
   qu'il passera inaperc,u pendant un moment, jusqu'`a ce que quelqu'un le
   re-categorise.

4. Ecrire le rapport de bogue

   Maintenant que vous avez decide que votre probleme merite un rapport de
   bogue, et que c'est un probleme avec FreeBSD, il est temps d'ecrire le
   rapport. Assurez-vous que votre variable d'environnement VISUAL (ou EDITOR
   si VISUAL n'existe pas) est configuree avec quelque chose de pratique, et
   lancez send-pr(1).

  4.1. Attacher des correctifs ou des fichiers

   Le programme send-pr(1) prevoit l'attachement de fichiers `a un rapport de
   bogue. Vous pouvez attacher autant de fichiers que vous le desirez `a
   condition que chacun ait un nom de base unique (i.e. le nom propre du
   fichier, sans le chemin). Utilisez juste l'option en ligne de commande -a
   pour specifier le nom des fichiers que vous souhaitez attacher:

 % send-pr -a /var/run/dmesg -a /tmp/errors

   Ne vous inquietez pas pour les fichiers binaires; ils seront
   automatiquement encodes de fac,on `a ne pas deranger votre logiciel de
   courrier.

   Si vous attachez un correctif, assurez-vous d'employer l'option -c ou -u
   avec diff(1) pour creer un fichier diff unifie ou contextuel, et soyez sur
   d'indiquer les numeros exacts des revisions CVS des fichiers que vous avez
   modifies afin que les developpeurs qui liront votre rapport soient
   capables d'appliquer facilement vos correctifs.

   Vous devez egalement prendre note `a moins que vous ne le precisiez
   explicitement dans votre PR, que tous les correctifs que vous soumettez
   seront presumes etre sous les memes termes de licence que le fichier
   original que vous avez modifie.

  4.2. Remplir le formulaire

   Le formulaire se compose d'une liste de champs, dont certains sont dej`a
   preremplis, et qui peuvent avoir des commentaires expliquant leur but et
   la liste des valeurs utilisables. Ne vous inquietez pas des commentaires;
   ils seront retires automatiquement si vous ne les modifiez ou retirez pas
   vous-meme.

   En haut du formulaire, sous les lignes SEND-PR:, se trouvent les entetes
   d'email. Vous n'avez normalement pas besoin de les modifier, `a moins que
   vous envoyiez le rapport de bogue `a partir d'une machine ou d'un compte
   qui peut envoyer mais pas recevoir de courrier, dans ce cas vous voudrez
   remplir les champs From: et Reply-To: suivant votre adresse email reelle.
   Vous pouvez vouloir vous envoyer (ou `a quelqu'un d'autre) une copie
   carbone du rapport de bogue en ajoutant une ou plusieurs adresses email au
   champ Cc:.

   Ensuite vient une serie de champ `a une ligne:

     * Submitter-Id: ne rien changer. La valeur par defaut current-users est
       correcte, meme si vous utilisez FreeBSD-STABLE.

     * Originator: ceci est normalement complete avec le champ gecos de
       l'utilisateur actuellement attache au systeme. Veuillez indiquer votre
       veritable nom, suivi optionnellement de votre email entre les symboles
       inferieur et superieur.

     * Organization: comme vous le sentez. Ce champ n'est pas employe pour
       quelque chose de significatif.

     * Confidential: ceci est prerempli avec no; le changer ne signifie pas
       grand chose car il n'y a aucun rapport de bogue confidentiel pour
       FreeBSD-la base de donnees des PRs est distribuee dans le monde entier
       par CVSup.

     * Synopsis: completez ceci avec une description courte et precise du
       probleme. Le synopsis est utilise comme sujet du rapport de bogue, et
       est employe dans les listes et resumes de rapport de bogue; les
       rapports de bogue avec d'obscures sujets ont tendance `a etre ignores.

       Si votre rapport de bogue inclus un correctif, veuillez utiliser un
       synopsis debutant avec le mot [PATCH].

     * Severity: une parmi non-critical, serious ou critical. Pas de
       surestimation, abstenez-vous de marquer votre probleme comme critical
       `a moins qu'il ne le soit vraiment (e.g. root exploit, panique du
       systeme facilement reproductible). Les developpeurs ont tendance `a
       ignorer ce champ et le suivant, precisement parce que les auteurs ont
       tendance `a surestimer l'importance de leurs problemes.

     * Priority: une parmi low, medium ou high. Voir ci-dessus.

     * Category: choisir l'une des suivantes:

          * advocacy: problemes concernant l'image publique de FreeBSD.
            Rarement utilise.

          * alpha: problemes specifiques `a la plateforme Alpha.

          * bin: problemes avec les programmes utilisateur du systeme de
            base.

          * conf: problemes avec les fichiers de configuration, les valeurs
            par defaut etc...

          * docs: problemes avec les pages de manuel ou la documentation en
            ligne.

          * gnu: problemes avec les logiciels GNU comme gcc(1) ou grep(1).

          * i386: problemes specifiques `a la plateforme i386.

          * kern: problemes avec le noyau.

          * misc: tout ce qui ne va pas dans une des autres categories.

          * ports: problemes concernant le catalogue des logiciels portes.

          * sparc: problemes specifiques `a la plate-forme Sparc.

     * Class: choisissez une des suivantes:

          * sw-bug: bogues logiciel.

          * doc-bug: erreurs dans la documentation.

          * change-request: demande de fonctionnalites supplementaires ou de
            changement dans des fonctionnalites existantes.

          * update: mise `a jour de logiciels portes ou d'autres logiciels.

          * maintainer-update: mise `a jour de logiciels portes dont vous
            etes le responsable.

     * Release: La version de FreeBSD que vous utilisez. Ceci sera complete
       automatiquement par send-pr(1) et devra etre modifie seulement si vous
       envoyez le rapport de bogue `a partir d'un systeme different de celui
       qui presente le probleme.

   Et enfin, il y a une serie de champs `a plusieurs lignes:

     * Environment: Ceci devrait decrire, le plus exactement que possible,
       l'environnement dans lequel le probleme a ete observe. Cela inclus la
       version du systeme d'exploitation, la version du programme specifique
       ou fichier qui contient le probleme, et tout autre element important
       comme la configuration du systeme, d'autres logiciels qui influencent
       le probleme, etc. - presque tout ce dont a besoin un developpeur pour
       reconstruire l'environnement dans lequel le probleme apparait.

     * Description: une description complete et precise du probleme que vous
       experimentez. Essayez d'eviter de speculer au sujet des causes du
       probleme `a moins que vous soyez certain d'etre dans le vrai, car cela
       peut tromper le developpeur.

     * How-To-Repeat: Un resume des actions necessaires pour reproduire le
       probleme.

     * Fix: De preference un correctif, ou au moins une solution de fortune
       (qui n'aidera pas seulement les autres personnes avec le meme
       probleme, mais peut aussi aider un developpeur `a comprendre la cause
       du probleme), mais si vous n'avez aucune idee pour l'un ou l'autre, il
       vaut mieux laisser ce champ en blanc plutot que de speculer.

  4.3. Envoi du rapport de bogue

   Une fois que vous avez rempli et sauvegarde le formulaire, puis quitte
   votre editeur, send-pr(1) vous proposera s)end, e)dit or a)bort? (envoyer,
   editer ou abandonner?). Vous pouvez alors taper s pour continuer et
   envoyer le rapport, e pour relancer l'editeur et faire d'autres
   modifications, ou encore a pour abandonner. Si vous choisissez cette
   derniere votre rapport de bogue restera sur le disque (send-pr(1) vous
   donnera le nom du fichier avant de terminer), ainsi vous pouvez l'editer
   `a loisir, ou peut-etre meme le transferer sur un systeme avec une
   meilleure connexion `a l'Internet, avant de l'envoyer avec l'option -f de
   send-pr(1):

 % send-pr -f ~/my-problem-report

   Il lira le fichier specifie, en validera le contenu, retirera les
   commentaires et l'enverra.

5. Suivi

   Une fois que votre rapport de bogue a ete classe, vous recevrez une
   confirmation par courrier qui contiendra le numero de suivi qui a ete
   assigne `a votre rapport de bogue et l'URL que vous pouvez utiliser pour
   verifier son statut. Avec un peu de chance, quelqu'un sera interesse par
   votre probleme et essaiera de s'en occuper, ou, quand ce sera le cas,
   expliquera pourquoi ce n'est pas un probleme. Vous serez automatiquement
   prevenu de tout changement d'etat, et vous recevrez des copies de tout
   commentaire ou correctif que quelqu'un pourra attacher au suivi de votre
   rapport de bogue.

   Si quelqu'un vous demande des informations supplementaires, ou vous vous
   rappelez ou decouvrez quelque chose que vous n'avez pas mentionne dans le
   rapport initial, envoyez-le juste `a <bug-followup@FreeBSD.org>, en vous
   assurant que le numero de suivi est inclus dans le sujet ainsi le systeme
   de suivi des bogues connaitra `a quel rapport de probleme l'attacher.

   Si le rapport de bogue reste ouvert apres que le probleme soit corrige,
   envoyez juste un courrier de suivi (de la maniere prescrite ci-dessus)
   disant que le rapport de bogue peut etre ferme, et, si possible,
   expliquant comment et quand le probleme fut corrige.

6. Lecture supplementaire

   Voici une liste des ressources concernant l'ecriture et le traitement
   appropries des rapports de bogue. Cela ne veut pas dire exhaustive.

     * Comment rapporter efficacement les bogues-un excellent essai de Simon
       G. Tatham sur l'ecriture de rapports de bogue utiles (non specifique
       `a FreeBSD).

Index

  R

   rapports de bogue, Ecrire des rapports de bogue pour FreeBSD
