4. Ecrire le rapport de bogue

4.1. Attacher des correctifs ou des fichiers

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

4.2. Remplir le formulaire

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.

4.3. Envoi du rapport de bogue

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.