$FreeBSD: head/fr_FR.ISO8859-1/articles/problem-reports/article.xml
39632 2012-10-01 11:56:00Z gabor $
Cet article décrit comment formuler et soumettre au mieux un rapport de bogue au projet FreeBSD.
Version française de Marc Fonvieille <[email protected]>.
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 “ce n'est pas un bogue” ou “PR bogué”. 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.
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.
Bien que l'objectif principal de cet article soit les rapports de bogue pour FreeBSD, sa majeure partie devrait s'appliquer relativement bien à d'autres projets de logiciels.
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-à-pas.
Il existe beaucoup de types de problèmes, et tous ne devraient pas être à 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'à 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 à propos de quelque chose d'autre qu'un bogue—une amélioration ou une demande de fonctionnalité, par exemple.
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 pas un bogue s'il peut être exprimé sous la forme d'une question (habituellement de la forme “Comment puis-je faire X?” ou “Où puis-je trouver Y?”). Ce n'est pas toujours aussi simple que cela, mais la règle de la question couvre une majorité de cas.
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:
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.
Avis de mise à jour de logiciels maintenus à l'extérieur (principalement des logiciels portés, mais également des composants du système de base maintenus à l'extérieur comme BIND ou divers utilitaires GNU).
Une autre chose est que si le système sur lequel vous expérimentez le bogue n'est pas suffisamment à jour, vous devriez considérer sérieusement de mettre à jour et d'essayer de reproduire le problème sur un système à 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à corrigé.
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 à un correctif sont très minces, et que vous devriez envisager de laisser tomber.
Une bonne règle à suivre est de toujours effectuer une recherche avant de soumettre un rapport de bogue. Peut-être que votre problème a déjà é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à 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:
La FAQ.
Les listes de diffusion—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 à ce sujet et attendre quelques jours pour voir si quelqu'un peut déceler quelque chose que vous n'avez pas remarqué.
Eventuellement, l'intégralité du web—utilisez votre moteur de recherche favoris pour chercher toutes les références à 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.
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à signalé.
Ensuite, vous devez être sûr que le rapport de bogue est envoyé aux bonnes personnes.
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 à l'auteur originel, et pas au projet FreeBSD. Il y a deux exceptions à 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à 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 à jour.
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'à ce que quelqu'un le re-catégorise.
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 VISUAL (ou EDITOR si VISUAL n'existe pas) est configurée avec quelque chose de pratique, et lancez send-pr(1).
Le programme send-pr(1) prévoit
l'attachement de fichiers à un rapport de bogue. Vous pouvez attacher autant de
fichiers que vous le désirez à 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 spécifier le nom des fichiers que
vous souhaitez attacher:
% send-pr -a /var/run/dmesg -a /tmp/errors
Ne vous inquiétez pas pour les fichiers binaires; ils seront automatiquement encodés de façon à ne pas déranger votre logiciel de courrier.
Si vous attachez un correctif, assurez-vous d'employer l'option -c ou -u avec 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.
Vous devez également prendre note à 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é.
Le formulaire se compose d'une liste de champs, dont certains sont déjà 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.
En haut du formulaire, sous les lignes SEND-PR:, se trouvent les entêtes d'émail. Vous n'avez normalement pas besoin de les modifier, à moins que vous envoyiez le rapport de bogue à 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 émail réelle. Vous pouvez vouloir vous envoyer (ou à quelqu'un d'autre) une copie carbone du rapport de bogue en ajoutant une ou plusieurs adresses émail au champ Cc:.
Ensuite vient une série de champ à une ligne:
Submitter-Id: ne rien changer. La valeur par défaut current-users est correcte, même si vous utilisez FreeBSD-STABLE.
Originator: 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.
Organization: comme vous le sentez. Ce champ n'est pas employé pour quelque chose de significatif.
Confidential: ceci est prérempli avec no; le changer ne signifie pas grand chose car il n'y a aucun rapport de bogue confidentiel pour FreeBSD—la base de données des PRs est distribuée dans le monde entier par CVSup.
Synopsis: 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 à être ignorés.
Si votre rapport de bogue inclus un correctif, veuillez utiliser un synopsis débutant avec le mot [PATCH].
Severity: une parmi non-critical, serious ou critical. Pas de surestimation, abstenez-vous de marquer votre problème comme critical à moins qu'il ne le soit vraiment (e.g. root exploit, panique du système facilement reproductible). Les développeurs ont tendance à ignorer ce champ et le suivant, précisément parce que les auteurs ont tendance à surestimer l'importance de leurs problèmes.
Priority: une parmi low, medium ou high. Voir ci-dessus.
Category: choisir l'une des suivantes:
advocacy: problèmes concernant l'image publique de FreeBSD. Rarement utilisé.
alpha: problèmes spécifiques à la plateforme Alpha.
bin: problèmes avec les programmes utilisateur du système de base.
conf: problèmes avec les fichiers de configuration, les valeurs par défaut etc...
docs: problèmes avec les pages de manuel ou la documentation en ligne.
gnu: problèmes avec les logiciels GNU comme gcc(1) ou grep(1).
i386: problèmes spécifiques à la plateforme i386.
kern: problèmes avec le noyau.
misc: tout ce qui ne va pas dans une des autres catégories.
ports: problèmes concernant le catalogue des logiciels portés.
sparc: problèmes spécifiques à la plate-forme Sparc.
Class: choisissez une des suivantes:
sw-bug: bogues logiciel.
doc-bug: erreurs dans la documentation.
change-request: demande de fonctionnalités supplémentaires ou de changement dans des fonctionnalités existantes.
update: mise à jour de logiciels portés ou d'autres logiciels.
maintainer-update: mise à jour de logiciels portés dont vous êtes le responsable.
Release: La version de FreeBSD que vous utilisez. Ceci sera complété automatiquement par send-pr(1) et devra être modifié seulement si vous envoyez le rapport de bogue à partir d'un système différent de celui qui présente le problème.
Et enfin, il y a une série de champs à plusieurs lignes:
Environment: 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. — presque tout ce dont a besoin un développeur pour reconstruire l'environnement dans lequel le problème apparaît.
Description: 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 à moins que vous soyez certain d'être dans le vrai, car cela peut tromper le développeur.
How-To-Repeat: Un résumé des actions nécessaires pour reproduire le problème.
Fix: 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 à 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.
Une fois que vous avez rempli et sauvegardé le formulaire, puis quitté votre
éditeur, send-pr(1) vous
proposera s)end, e)dit or a)bort? (envoyer, éditer
ou abandonner?). Vous pouvez alors taper s pour
continuer et envoyer le rapport, e pour relancer
l'éditeur et faire d'autres modifications, ou encore a
pour abandonner. Si vous choisissez cette dernière votre rapport de bogue restera
sur le disque (send-pr(1) vous
donnera le nom du fichier avant de terminer), ainsi vous pouvez l'éditer à loisir,
ou peut-être même le transférer sur un système avec une meilleure
connexion à l'Internet, avant de l'envoyer avec l'option -f de send-pr(1):
% send-pr -f ~/my-problem-report
Il lira le fichier spécifié, en validera le contenu, retirera les commentaires et l'enverra.
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é à 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.
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 à <[email protected]>, en vous
assurant que le numéro de suivi est inclus dans le sujet ainsi le système de suivi des
bogues connaîtra à quel rapport de problème l'attacher.
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é.
Voici une liste des ressources concernant l'écriture et le traitement appropriés des rapports de bogue. Cela ne veut pas dire exhaustive.
Comment rapporter efficacement les bogues—un excellent essai de Simon G. Tatham sur l'écriture de rapports de bogue utiles (non spécifique à FreeBSD).
Ce document, ainsi que d'autres peut être téléchargé sur ftp.FreeBSD.org/pub/FreeBSD/doc/.
Pour toutes questions à propos de FreeBSD, lisez la documentation avant de contacter <[email protected]>.
Pour les questions sur cette documentation, contactez <[email protected]>.