               Ecrire des rapports de bogue pour FreeBSD

  Dag-Erling Smo/rgrav

   $FreeBSD:
   doc/fr_FR.ISO8859-1/articles/problem-reports/article.sgml,v 1.3
   2007/01/19 21:27:58 blackend Exp $

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

   La redistribution du code source (SGML), modifie ou non, et
   compile (HTML, PostScript, etc.) est soumise aux conditions
   suivantes :

    1. Le copyright ci-dessus, la presente liste de conditions et
       l'avertissement qui la suit doivent figurer dans le code
       source.

    2. Le code source distribue sous forme compilee doit faire
       apparaitre le copyright ci-dessus, la presente liste de
       conditions et l'avertissement qui la suit.

   CE DOCUMENT EST FOURNI ``TEL QU'EN L'ETAT'' PAR LE PROJET DE
   DOCUMENTATION FRANC,AISE DE FreeBSD ET IL N'EST DONNE AUCUNE
   GARANTIE, IMPLICITE OU EXPLICITE, QUANT A SON UTILISATION
   COMMERCIALE, PROFESSIONNELLE OU AUTRE. LES COLLABORATEURS DU
   PROJET DE DOCUMENTATION FRANC,AISE DE FreeBSD NE PEUVENT EN AUCUN
   CAS ETRE TENUS POUR RESPONSABLES DE QUELQUE DOMMAGE OU PREJUDICE
   DIRECT, INDIRECT, SECONDAIRE OU ACCESSOIRE (Y COMPRIS LES PERTES
   FINANCIeRES DUES AU MANQUE A GAGNER, A L'INTERRUPTION D'ACTIVITES,
   OU LA PERTE D'INFORMATIONS ET AUTRES) DECOULANT DE L'UTILISATION
   DE LA DOCUMENTATION OU DE L'IMPOSSIBILITE D'UTILISER CELLE-CI, ET
   DONT L'UTILISATEUR ACCEPTE L'ENTIERE RESPONSABILITE.

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

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

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

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).

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

        Ce document, ainsi que d'autres peut etre telecharge sur
                   ftp.FreeBSD.org/pub/FreeBSD/doc/.

Pour toutes questions `a propos de FreeBSD, lisez la documentation avant
                 de contacter <questions@FreeBSD.org>.
Pour les questions sur cette documentation, contactez <doc@FreeBSD.org>.
