doc/fr_FR.ISO8859-1/articles/problem-reports/article.sgml

<?xml version="1.0" encoding="iso-8859-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>