path: root/fr_FR.ISO8859-1/articles/problem-reports/article.sgml

<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/sgml/freebsd42.dtd" [
<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//FR" "../../share/sgml/entities.ent">
%entities;
]>

<!--                                                                     
    The FreeBSD Documentation Project                                    
    The FreeBSD French Documentation Project                             

    $FreeBSD$
    $Id: article.sgml,v 1.3 2007-01-19 21:27:58 blackend Exp $
    Original revision: 1.10
-->

<article lang="fr">
  <articleinfo>
    <title>Ecrire des rapports de bogue pour FreeBSD</title>

    <abstract>
      <para>Cet article décrit comment formuler et soumettre au mieux un 
	rapport	de bogue au projet FreeBSD.</para>

	&trans.a.fonvieille;
    </abstract>

    <authorgroup>
      <author>
	<firstname>Dag-Erling</firstname>
	<surname>Sm&oslash;rgrav</surname>
	<contrib>Contributed by </contrib>
      </author>
    </authorgroup>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD$</releaseinfo>
  </articleinfo>

  <indexterm><primary>rapports de bogue</primary></indexterm>

  <sect1 id="pr-intro">
    <title>Introduction</title>

    <para>Une des expériences la plus frustrante que peut vivre un
      utilisateur de logiciel est de soumettre un rapport de bogue et de
      le voir être fermé sommairement avec une explication 
      laconique et sans aide du type &ldquo;ce n'est pas un bogue&rdquo; ou
      &ldquo;PR bogué&rdquo;.  De même une des 
      expériences la plus frustrante pour un programmeur est 
      d'être submergé de rapports de
      bogue qui ne sont pas vraiment des rapports de bogue mais plutôt
      des demandes d'aide, ou qui contiennent peu ou pas d'information
      au sujet du problème et sur comment le reproduire.</para>

    <para>Ce document essaye de décrire comment écrire 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 être analysé et 
      traité rapidement, pour la satisfaction mutuelle de 
      l'utilisateur et du développeur.</para>

    <para>Bien que l'objectif principal de cet article soit les rapports
      de bogue pour FreeBSD, sa majeure partie devrait s'appliquer
      relativement bien &agrave; d'autres projets de logiciels.</para>

    <para>Notez que cet article est organisé thématiquement, 
      et non pas de façon chronologique, ainsi vous devriez lire 
      entièrement ce document avant de soumettre un rapport de 
      bogue, plutôt que de le traiter comme un guide 
      pas-&agrave;-pas.</para>
  </sect1>

  <sect1 id="pr-when">
    <title>Quand soumettre un rapport de bogue</title>

    <para>Il existe beaucoup de types de problèmes, et tous ne 
      devraient pas être &agrave; l'origine d'un rapport de bogue.  
      Naturellement, personne n'est parfait, et il y aura des moments 
      où vous serez convaincus d'avoir trouvé 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 être significatif 
      d'une documentation sommaire ou d'une mauvaise gestion des erreurs 
      dans l'application).  Il reste beaucoup de cas où la 
      soumission d'un rapport de bogue n'est clairement pas la bonne 
      ligne de conduite, et ne servira qu'&agrave; frustrer les 
      développeurs et vous-même.  Réciproquement, il y a
      des cas où il peut être approprié de 
      soumettre un rapport de bogue &agrave; propos de quelque chose 
      d'autre qu'un bogue&mdash;une amélioration ou une demande 
      de fonctionnalité, par exemple.</para>

    <para>Aussi comment déterminer ce qui est un bogue et ce qui ne
      l'est pas?  Un principe de base simple est que votre problème
      n'est <emphasis>pas</emphasis> un bogue s'il peut être 
      exprimé sous la forme d'une question (habituellement de la 
      forme &ldquo;Comment puis-je faire X?&rdquo; ou &ldquo;Où 
      puis-je trouver Y?&rdquo;).  Ce n'est pas toujours aussi simple 
      que cela, mais la règle de la question couvre une 
      majorité de cas.</para>

    <para>Les quelques cas où il peut être approprié 
      de soumettre un rapport de bogue au sujet de quelque chose qui 
      n'est pas un bogue sont:</para>

    <itemizedlist>
      <listitem>
        <para>demandes d'amélioration de caractéristiques.  
	  C'est généralement une bonne idée de 
	  discuter de cela sur les listes de diffusion avant de 
	  soumettre un rapport de bogue.</para>
      </listitem>

      <listitem>
        <para>Avis de mise &agrave; jour de logiciels maintenus &agrave; 
	  l'extérieur (principalement des logiciels portés, 
	  mais également des composants du système de base 
	  maintenus &agrave; l'extérieur comme BIND ou divers 
	  utilitaires GNU).</para>
      </listitem>
    </itemizedlist>

    <para>Une autre chose est que si le système sur lequel vous
      expérimentez le bogue n'est pas suffisamment &agrave; jour, 
      vous devriez considérer sérieusement de mettre 
      &agrave; jour et d'essayer de reproduire le problème sur 
      un système &agrave; jour avant de soumettre le
      rapport de bogue.  Il y peu de choses qui ennuieront plus un
      développeur que de recevoir un rapport de bogue au sujet
      d'un problème déj&agrave; corrigé.</para>

    <para>Et finalement, un bogue qui ne peut être reproduit peut
      rarement être corrigé.  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
      développeurs 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 plutôt que les chances que votre rapport de bogue 
      mène &agrave; un correctif sont très minces, et que 
      vous devriez envisager de laisser tomber.</para>
  </sect1>

  <sect1 id="pr-prep">
    <title>Préparations</title>

    <para>Une bonne règle &agrave; suivre est de toujours 
      effectuer une recherche avant de soumettre un rapport de bogue.  
      Peut-être que votre problème a déj&agrave; 
      été signalé; peut-être même qu'on en
      discute actuellement sur les listes de diffusion, ou l'était
      récemment; il se peut qu'il soit même déj&agrave; 
      corrigé dans une nouvelle version de ce que vous utilisez.  
      Vous devriez donc vérifier tous les lieux d'information 
      avant de soumettre votre rapport de bogue.  Pour FreeBSD, cela 
      signifie:</para>

    <itemizedlist>
      <listitem>
        <para>La FAQ.</para>
      </listitem>

      <listitem>
        <para>Les listes de diffusion&mdash;si vous n'êtes pas inscrit,
	  utilisez l'outil de recherche des archives sur le site de
	  FreeBSD.  Si votre problème n'a pas été 
	  abordé sur les listes, vous pourriez essayer de poster 
	  un message &agrave; ce sujet et attendre quelques jours pour 
	  voir si quelqu'un peut déceler quelque chose que vous 
	  n'avez pas remarqué.</para>
      </listitem>

      <listitem>
        <para>Eventuellement, l'intégralité du 
	  web&mdash;utilisez votre moteur de recherche favoris pour 
	  chercher toutes les références &agrave; votre 
	  problème.  Vous pouvez même obtenir des
	  résultats des archives des listes de diffusion ou des forums
	  de discussion que vous ne connaissiez pas ou parmi lesquels
	  vous n'aviez pas pensé chercher.</para>
      </listitem>

      <listitem>
        <para>Et finalement, la base de données des PRs.  A 
	  moins que votre problème ne soit récent ou 
	  obscure, il y a assez de chance pour qu'il soit 
	  déj&agrave; signalé.</para>
      </listitem>
    </itemizedlist>

    <para>Ensuite, vous devez être sûr que le rapport de 
      bogue est envoyé aux bonnes personnes.</para>

    <para>Le premier point ici est que si un problème est un 
      bogue dans un logiciel tiers (un logiciel porté ou 
      pré-compilé que vous avez installé), vous 
      devrez rapporter le bogue &agrave; l'auteur originel, et
      pas au projet FreeBSD.  Il y a deux exceptions &agrave; cette 
      règle: la première est que si le bogue 
      n'apparaît pas sur d'autres plate-formes, dans quel cas le 
      problème peut venir de la façon dont le logiciel a 
      été porté sous FreeBSD; la seconde est si 
      l'auteur original a déj&agrave; corrigé le 
      problème et sorti un correctif ou une nouvelle version de 
      son logiciel, et que le logiciel porté de
      FreeBSD n'a pas encore été mis &agrave; jour.</para>

    <para>Le second point est que le système de suivi des bogues de
      FreeBSD classe les rapports de bogue en fonction de la 
      catégorie que l'auteur a choisie.  Donc, si vous choisissez 
      la mauvaise catégorie, il y a de fortes chances qu'il 
      passera inaperçu pendant un moment, jusqu'&agrave; ce que 
      quelqu'un le re-catégorise.</para>
  </sect1>

  <sect1 id="pr-writing">
    <title>Ecrire le rapport de bogue</title>

    <para>Maintenant que vous avez décidé que votre 
      problème mérite un rapport de bogue, et que c'est 
      un problème avec FreeBSD, il est temps d'écrire 
      le rapport.  Assurez-vous que votre variable d'environnement 
      <envar>VISUAL</envar> (ou <envar>EDITOR</envar> si
      <envar>VISUAL</envar> n'existe pas) est configurée avec 
      quelque chose de pratique, et lancez &man.send-pr.1;.</para>

    <sect2>
      <title>Attacher des correctifs ou des fichiers</title>

      <para>Le programme &man.send-pr.1; prévoit l'attachement de
	fichiers &agrave; un rapport de bogue.  Vous pouvez attacher 
	autant de fichiers que vous le désirez &agrave; 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 <option>-a</option> pour spécifier le nom des 
	fichiers que vous souhaitez attacher:</para>

<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput>
</screen>

      <para>Ne vous inquiétez pas pour les fichiers binaires; 
	ils seront automatiquement encodés de façon 
	&agrave; ne pas déranger votre logiciel de courrier.</para>

      <para>Si vous attachez un correctif, assurez-vous d'employer
	l'option <option>-c</option> ou <option>-u</option> avec
	&man.diff.1; pour créer un fichier diff unifié 
	ou contextuel, et soyez sûr d'indiquer les numéros 
	exacts des révisions CVS des fichiers que vous avez 
	modifiés afin que les développeurs qui
	liront votre rapport soient capables d'appliquer facilement vos
	correctifs.</para>

      <para>Vous devez également prendre note &agrave; moins que 
	vous ne le précisiez explicitement dans votre PR, que 
	tous les correctifs que vous soumettez seront 
	présumés être sous les mêmes termes de
	licence que le fichier original que vous avez modifié.</para>
    </sect2>

    <sect2>
      <title>Remplir le formulaire</title>

      <para>Le formulaire se compose d'une liste de champs, dont
	certains sont déj&agrave; préremplis, et qui 
	peuvent avoir des commentaires expliquant leur but et la liste 
	des valeurs utilisables.  Ne vous inquiétez pas des 
	commentaires; ils seront retirés automatiquement si vous 
	ne les modifiez ou retirez pas vous-même.</para>

      <para>En haut du formulaire, sous les lignes
        <literal>SEND-PR:</literal>, se trouvent les entêtes
	d'émail.  Vous n'avez normalement pas besoin de les 
	modifier, &agrave; moins que vous envoyiez le rapport de bogue 
	&agrave; partir d'une machine ou d'un compte qui peut envoyer 
	mais pas recevoir de courrier, dans ce cas vous voudrez remplir 
	les champs <literal>From:</literal> et <literal>Reply-To:</literal> 
	suivant votre adresse émail réelle.  Vous pouvez 
	vouloir vous envoyer (ou &agrave; quelqu'un d'autre) une copie 
	carbone du rapport de bogue en ajoutant une ou plusieurs 
	adresses émail au champ <literal>Cc:</literal>.</para>

      <para>Ensuite vient une série de champ &agrave; une ligne:</para>

      <itemizedlist>
        <listitem>
	  <para><emphasis>Submitter-Id:</emphasis> ne rien changer.
	    La valeur par défaut <literal>current-users</literal> est
	    correcte, même si vous utilisez FreeBSD-STABLE.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Originator:</emphasis> ceci est normalement
	    complété avec le champ gecos de l'utilisateur 
	    actuellement attaché au système.  Veuillez 
	    indiquer votre véritable nom,
	    suivi optionnellement de votre émail entre les symboles
	    inférieur et supérieur.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Organization:</emphasis> comme vous le sentez.
	    Ce champ n'est pas employé pour quelque chose de
	    significatif.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Confidential:</emphasis> ceci est prérempli
	    avec <literal>no</literal>; le changer ne signifie pas grand
	    chose car il n'y a aucun rapport de bogue confidentiel pour
	    FreeBSD&mdash;la base de données des PRs est 
	    distribuée dans le monde entier par CVSup.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Synopsis:</emphasis> complétez ceci 
	    avec une description courte et précise du 
	    problème.  Le synopsis est utilisé comme sujet 
	    du rapport de bogue, et est employé dans
	    les listes et résumés de rapport de bogue; les 
	    rapports de bogue avec d'obscures sujets ont tendance &agrave; 
	    être ignorés.</para> 

	  <para>Si votre rapport de bogue inclus un correctif, veuillez
	    utiliser un synopsis débutant avec le mot
	    <literal>[PATCH]</literal>.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Severity:</emphasis> une parmi
  	    <literal>non-critical</literal>,
  	    <literal>serious</literal> ou
  	    <literal>critical</literal>.  Pas de surestimation,
	    abstenez-vous de marquer votre problème comme
	    <literal>critical</literal> &agrave; moins qu'il ne le soit
	    vraiment (e.g. root exploit, panique du système facilement
	    reproductible).  Les développeurs ont tendance &agrave; 
	    ignorer ce champ et le suivant, précisément parce 
	    que les auteurs ont tendance &agrave; surestimer l'importance 
	    de leurs problèmes.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Priority:</emphasis> une parmi
  	    <literal>low</literal>, <literal>medium</literal> ou
  	    <literal>high</literal>.  Voir ci-dessus.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Category:</emphasis> choisir l'une des
	    suivantes:</para>
	  <itemizedlist>
	    <listitem>
	      <para><literal>advocacy:</literal> problèmes concernant
	        l'image publique de FreeBSD.  Rarement utilisé.</para>
	    </listitem>

	    <listitem>
	      <para><literal>alpha:</literal> problèmes 
		spécifiques &agrave; la
	        plateforme Alpha.</para>
	    </listitem>

	    <listitem>
	      <para><literal>bin:</literal> problèmes avec les
		programmes utilisateur du système de base.</para>
	    </listitem>

	    <listitem>
	      <para><literal>conf:</literal> problèmes avec les fichiers
		de configuration, les valeurs par défaut etc...</para>
	    </listitem>

	    <listitem>
	      <para><literal>docs:</literal> problèmes avec les pages de
		manuel ou la documentation en ligne.</para>
	    </listitem>

	    <listitem>
	      <para><literal>gnu:</literal> problèmes avec les logiciels 
		GNU comme &man.gcc.1; ou &man.grep.1;.</para>
	    </listitem>

	    <listitem>
	      <para><literal>i386:</literal> problèmes 
		spécifiques &agrave; la
		plateforme i386.</para>
	    </listitem>

	    <listitem>
	      <para><literal>kern:</literal> problèmes avec le
		noyau.</para>
	    </listitem>

	    <listitem>
	      <para><literal>misc:</literal> tout ce qui ne va pas dans
		une des autres catégories.</para>
	    </listitem>
	
	    <listitem>
	      <para><literal>ports:</literal> problèmes concernant le
		catalogue des logiciels portés.</para>
	    </listitem>
	
	    <listitem>
	      <para><literal>sparc:</literal> problèmes 
		spécifiques &agrave; la
		plate-forme Sparc.</para>
	    </listitem>
	  </itemizedlist>
	</listitem>
	
	<listitem>
	  <para><emphasis>Class:</emphasis> choisissez une des
	    suivantes:</para>
	
	  <itemizedlist>
	    <listitem>
	      <para><literal>sw-bug:</literal> bogues logiciel.</para>
	    </listitem>
	
	    <listitem>
	      <para><literal>doc-bug:</literal> erreurs dans la
	        documentation.</para>
	    </listitem>
	
	    <listitem>
	      <para><literal>change-request:</literal> demande de
		fonctionnalités supplémentaires ou de 
		changement dans
		des fonctionnalités existantes.</para>
	    </listitem>
	
	    <listitem>
	      <para><literal>update:</literal> mise &agrave; jour de logiciels
		portés ou d'autres logiciels.</para>
	    </listitem>
	
	    <listitem>
	      <para><literal>maintainer-update:</literal> mise &agrave; 
		jour de logiciels portés dont vous êtes le 
		responsable.</para>
	    </listitem>
	  </itemizedlist>
	</listitem>

	<listitem>
	  <para><emphasis>Release:</emphasis> La version de FreeBSD que
	    vous utilisez.  Ceci sera complété 
	    automatiquement par &man.send-pr.1; et devra être 
	    modifié seulement si vous envoyez le rapport de 
	    bogue &agrave; partir d'un système différent
	    de celui qui présente le problème.</para>
	</listitem>
      </itemizedlist>

      <para>Et enfin, il y a une série de champs &agrave; plusieurs
	lignes:</para>

      <itemizedlist>
        <listitem>
	  <para><emphasis>Environment:</emphasis> Ceci devrait décrire,
	    le plus exactement que possible, l'environnement dans lequel
	    le problème a été observé.  Cela 
	    inclus la version du système d'exploitation, la version 
	    du programme spécifique
	    ou fichier qui contient le problème, et tout autre 
	    élément
	    important comme la configuration du système, d'autres
	    logiciels qui influencent le problème, etc. &mdash;
	    presque tout ce dont a besoin un développeur pour
	    reconstruire l'environnement dans lequel le problème
	    apparaît.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Description:</emphasis> une description
	    complète et précise du problème que vous 
	    expérimentez.
	    Essayez d'éviter de spéculer au sujet des causes 
	    du problème &agrave; moins que vous soyez certain 
	    d'être dans le vrai, car cela
	    peut tromper le développeur.</para>
	</listitem>

	<listitem>
	  <para><emphasis>How-To-Repeat:</emphasis> Un résumé 
	    des actions nécessaires pour reproduire le 
	    problème.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Fix:</emphasis> De préférence un 
	    correctif, ou au moins une solution de fortune (qui n'aidera 
	    pas seulement les autres personnes avec le même 
	    problème, mais peut aussi
	    aider un développeur &agrave; comprendre la cause du 
	    problème),
	    mais si vous n'avez aucune idée pour l'un ou l'autre, il
	    vaut mieux laisser ce champ en blanc plutôt que de
	    spéculer.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Envoi du rapport de bogue</title>

      <para>Une fois que vous avez rempli et sauvegardé le formulaire,
	puis quitté votre éditeur, &man.send-pr.1; vous 
	proposera
	<prompt>s)end, e)dit or a)bort?</prompt> (envoyer, éditer ou
	abandonner?).  Vous pouvez alors taper <userinput>s</userinput>
	pour continuer et envoyer le rapport, <userinput>e</userinput>
	pour relancer l'éditeur et faire d'autres modifications, ou
	encore <userinput>a</userinput> pour abandonner.  Si vous
	choisissez cette dernière votre rapport de bogue restera sur le
	disque (&man.send-pr.1; vous donnera le nom du fichier avant de
	terminer), ainsi vous pouvez l'éditer &agrave; loisir, 
	ou peut-être
	même le transférer sur un système avec une 
	meilleure connexion &agrave;
	l'Internet, avant de l'envoyer avec l'option <option>-f</option>
	de &man.send-pr.1;:</para>

<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen>

      <para>Il lira le fichier spécifié, en validera le contenu,
	retirera les commentaires et l'enverra.</para>
    </sect2>

  </sect1>

  <sect1 id="pr-followup">
    <title>Suivi</title>

    <para>Une fois que votre rapport de bogue a été 
      classé, vous
      recevrez une confirmation par courrier qui contiendra le 
      numéro de suivi qui a été assigné 
      &agrave; votre rapport de bogue et l'URL que vous
      pouvez utiliser pour vérifier son statut.  Avec un peu de chance,
      quelqu'un sera intéressé par votre problème et 
      essaiera de s'en
      occuper, ou, quand ce sera le cas, expliquera pourquoi ce n'est
      pas un problème.  Vous serez automatiquement prévenu 
      de tout changement d'état, et vous recevrez des copies de 
      tout commentaire
      ou correctif que quelqu'un pourra attacher au suivi de votre
      rapport de bogue.</para>

    <para>Si quelqu'un vous demande des informations supplémentaires, ou
      vous vous rappelez ou découvrez quelque chose que vous n'avez pas
      mentionné dans le rapport initial, envoyez-le juste &agrave;
      <email>bug-followup@FreeBSD.org</email>, en vous assurant que le
      numéro de suivi est inclus dans le sujet ainsi le système 
      de suivi des bogues connaîtra &agrave; quel rapport de 
      problème l'attacher.</para>

    <para>Si le rapport de bogue reste ouvert après que le 
      problème soit
      corrigé, envoyez juste un courrier de suivi (de la manière
      prescrite ci-dessus) disant que le rapport de bogue peut être
      fermé, et, si possible, expliquant comment et quand le 
      problème
      fut corrigé.</para>
  </sect1>

  <sect1 id="pr-further">
    <title>Lecture supplémentaire</title>

    <para>Voici une liste des ressources concernant l'écriture et le
      traitement appropriés des rapports de bogue.  Cela ne veut pas
      dire exhaustive.</para>

    <itemizedlist>
      <listitem>
        <para><ulink
	    url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
	    Comment rapporter efficacement les bogues</ulink>&mdash;un 
	    excellent essai de Simon G. Tatham sur l'écriture de 
	    rapports de bogue utiles
	    (non spécifique &agrave; FreeBSD).</para>
      </listitem>
    </itemizedlist>
  </sect1>
</article>