+
+ <sect id="bpp-debian-control">
+ <heading>Les meilleures pratiques pour le fichier
+ <file>debian/control</file></heading>
+ <p>
+Les pratiques suivantes sont relatives au fichier <file>debian/control</file>.
+Elles viennent en complément des <url
+id="&url-debian-policy;ch-miscellaneous.html#s-descriptions" name="règles pour
+les descriptions de paquet">.
+<p>
+La description du paquet, telle qu'elle est définie par le champ correspondant
+dans le fichier <file>control</file>, contient à la fois le résumé du paquet et
+la description longue pour le paquet. <ref id="bpp-desc-basics"> décrit des
+lignes générales pour les deux parties de la description. Ensuite, <ref
+id="bpp-pkg-synopsis"> fournit des principes spécifiques pour le résumé et <ref
+id="bpp-pkg-desc"> contient des principes spécifiques pour la description
+longue.
+
+ <sect1 id="bpp-desc-basics">
+ <heading>Les règles générales pour les descriptions des paquets</heading>
+<p>
+La description du paquet devrait être écrite pour l'utilisateur moyen,
+l'utilisateur qui va utiliser et bénéficier du paquet. Par exemple, les paquets
+de développement sont pour les développeurs et leur description peut utiliser un
+langage technique. Pour les applications à but plus général comme un éditeur, la
+description devrait être écrite pour un non-spécialiste.
+<p>
+Notre critique des descriptions des paquets nous amène à conclure que la plupart
+des descriptions des paquets sont techniques, c'est-à-dire, qu'elles ne sont pas
+écrites pour être comprises par les non-spécialistes. À moins que
+votre paquet ne soit que pour les techniciens, c'est un problème.
+<p>
+Comment écrire pour les non-spécialistes ? Évitez le jargon.
+Évitez de vous référer à d'autres applications et cadres de travail avec
+lesquels l'utilisateur n'est pas forcément familier — « GNOME »
+ou « KDE » sont corrects car les utilisateurs sont probablement
+familiers avec ces termes, mais « GTK+ » ne l'est probablement pas.
+Ne supposez aucune connaissance. Si vous devez utiliser des termes techniques,
+introduisez-les.
+<p>
+Soyez objectif. Les descriptions de paquet ne sont pas un endroit pour
+promouvoir votre paquet, quel que soit l'amour que vous lui portez.
+Rappelez-vous que le lecteur n'a pas forcément les mêmes priorités que vous.
+<p>
+Des références aux noms de tout autre paquet de logiciels, noms de protocoles,
+standards ou spécifications devraient utiliser leurs formes canoniques si elles
+existent. Par exemple, utilisez « X Window System », « X11 »
+ou « X » et non « X Windows », « X-Windows » ou
+« X Window ». Utilisez « GTK+ » et non « GTK » ou
+« gtk ». Utilisez « GNOME » et non « Gnome ».
+Utilisez « PostScript » et non « Postscript » ou
+« postscript ».
+<p>
+Si vous avez des problèmes pour écrire votre description, vous pouvez l'envoyer à
+&email-debian-l10n-english; et demander un retour d'informations.
+
+ </sect1>
+
+<sect1 id="bpp-pkg-synopsis">
+ <heading>Le résumé du paquet ou description courte</heading>
+<p>
+La ligne de résumé (la description courte) devrait être concise. Elle ne doit
+pas répéter le nom du paquet (c'est une règle).
+<p>
+C'est une bonne idée de penser au résumé comme à une clause apposée et non une
+phrase complète. Une clause apposée est définie dans WordNet comme une relation
+grammaticale entre un mot et une phrase pronominale qui la suit, par exemple
+« Rudolph, le renne au nez rouge ». La clause apposée ici est
+« le renne au nez rouge ». Comme le résumé est une clause et non une
+phrase complète, nous recommandons de ne pas la commencer par une majuscule et
+de ne pas la finir par un point. Il ne doit pas non plus commencer avec un
+article, défini (« le ») ou indéfini (« un »).
+<p>
+Cela peut vous aider d'imaginer le résumé combiné avec le nom du paquet de
+la façon suivante :
+
+<example><var>nom-paquet</var> est un <var>résumé</var>.</example>
+
+Sinon, il peut être plus compréhensible de le voir comme
+
+<example><var>nom-paquet</var> est <var>résumé</var>.</example>
+
+ou, si le nom du paquet est lui-même un pluriel (comme
+« developer-tools »)
+
+<example><var>nom-paquet</var> sont <var>résumé</var>.</example>
+
+Cette façon de former une phrase à partir du nom du paquet et du résumé devrait
+être considérée comme une heuristique et non comme une règle stricte. Il y a
+certains cas où cela n'a aucun sens de former une phrase.
+
+ </sect1>
+
+ <sect1 id="bpp-pkg-desc">
+ <heading>La description longue</heading>
+<p>
+La description longue du paquet est la première information dont dispose
+l'utilisateur avant d'installer un paquet. Aussi, elle devrait fournir toutes
+les informations nécessaires pour le laisser décider de l'installation du
+paquet. Vous pouvez supposer que l'utilisateur a déjà lu le résumé du paquet.
+<p>
+La description longue devrait toujours être constituée de phrases complètes.
+<p>
+Le premier paragraphe de la description longue devrait répondre aux questions
+suivantes : qu'est-ce que fait le paquet ? Quelle tâche aide-t-il
+l'utilisateur à accomplir ? Il est important de décrire ceci d'une manière
+non technique, à moins que le paquet ne s'adresse qu'à un auditoire de techniciens.
+<p>
+Les paragraphes suivants devraient répondre aux questions suivantes :
+Pourquoi, en tant qu'utilisateur, ai-je besoin de ce paquet ? Quelles
+sont les autres fonctionnalités dont dispose le paquet ? Quelles
+sont les fonctionnalités marquantes et les déficiences de ce paquet comparé à
+d'autres paquets (par exemple, « si vous avez besoin de X, utilisez Y à la
+place ») ? Est-ce que le paquet est lié à d'autres paquets d'une
+certaine façon qui n'est pas gérée par le gestionnaire de paquet (par exemple,
+« il s'agit d'un client pour le serveur foo ») ?
+<p>
+Soyez attentif à éviter les fautes d'orthographe et de grammaire. N'oubliez
+pas votre vérificateur orthographique. <prgn>ispell</prgn> possède une option
+spéciale (<tt>-g</tt>) pour cela :
+
+<example>ispell -d american -g debian/control</example>
+
+ </sect1>
+
+ <sect1 id="bpp-upstream-info">
+ <heading>Page d'accueil amont</heading>
+ <p>
+Nous vous recommandons d'ajouter l'adresse de la page d'accueil du paquet à la
+description du paquet dans le fichier <file>debian/control</file>. Cette
+information devrait être ajoutée à la fin de la description en utilisant le
+format suivant :
+
+<example> .
+ Homepage: http://some-project.some-place.org/</example>
+
+Veuillez noter les espaces au début de la ligne, ils servent à séparer les
+lignes correctement. Pour voir un exemple de ce que cela affiche, veuillez vous
+reporter à <url id="&url-eg-desc-upstream-info;">.
+ <p>
+Ne mettez rien s'il n'existe pas de page pour le logiciel.
+
+ <p>
+Veuillez noter que nous espérons que ce champ sera remplacé par un
+vrai champ de <file>debian/control</file> que comprendraient <prgn>dpkg</prgn>
+et <tt>&packages-host;</tt>. Si vous ne voulez pas vous embêter à déplacer la
+page d'accueil depuis la description vers ce nouveau champ, vous devriez
+probablement attendre qu'il soit disponible.</p>
+ </sect1>
+ </sect>
+
+
+ <sect id="bpp-debian-changelog">
+ <heading>Les meilleures pratiques pour le fichier <file>debian/changelog</file></heading>
+ <p>
+Les pratiques suivantes viennent en complément de la <url name="directive sur
+les fichiers changelog" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
+
+ <sect1 id="bpp-changelog-do">
+ <heading>Écrire des entrées de changelog utiles</heading>
+ <p>
+L'entrée de changelog pour une révision de paquet documente les changements dans
+cette révision et seulement ceux-ci. Concentrez-vous sur la description des
+changements significatifs et visibles de l'utilisateur qui ont été effectués
+depuis la dernière version.
+ <p>
+Ciblez <em>ce</em> qui a été changé — qui, comment et quand cela a été fait
+est généralement de moindre importance. Ceci dit, rappelez-vous de nommer
+poliment les personnes qui ont fourni une aide notable pour réaliser le
+paquet (par exemple, ceux qui ont envoyé des correctifs).
+ <p>
+Vous n'avez pas besoin de détailler les changements triviaux et évidents. Vous
+pouvez également regrouper plusieurs de ces changements dans une seule entrée.
+D'un autre côté, ne soyez pas trop concis si vous avez entrepris un changement
+majeur. Soyez tout spécialement clair s'il y a des changements qui modifient le
+comportement du programme. Pour plus d'explications, utilisez le fichier
+<file>README.Debian</file>.
+ <p>
+Utilisez un langage anglais commun pour que la majorité des lecteur puissent le
+comprendre. Évitez les abbréviations, le parler technique et le jargon quand
+vous expliquez des changements fermant un bogue, spécialement pour les rapports
+de bogue créés par des utilisateurs qui ne vous paraissent pas particulièrement
+à l'aise techniquement. Vous devez être poli et ne pas jurer.
+ <p>
+Il est parfois désirable de préfixer les entrées de changelog avec le nom des
+fichiers qui ont été modifiés. Cependant, il n'est pas besoin de lister
+explicitement tous les fichiers modifiés, particulièrement si la modification
+est petite ou répétitive. Vous pouvez utiliser les caractères génériques.
+ <p>
+Quand vous faites référence aux bogues, ne supposez rien a priori. Dites ce
+qu'était le problème, comment il a été résolu et ajoutez la chaîne de caractères
+« closes: #nnnnn ». Veuillez voir <ref id="upload-bugfix"> pour plus
+d'informations.
+
+ <sect1 id="bpp-changelog-misconceptions">
+ <heading>Communes idées fausses sur les entrées de changelog</heading>
+ <p>
+Les entrées de changelog <strong>ne devraient pas</strong> documenter des
+problèmes génériques d'empaquetage (« Hé, si vous cherchez foo.conf, il
+est dans /etc/blah/. ») car les administrateurs et utilisateurs sont
+supposés être au moins vaguement rompus à la façon dont les choses sont
+arrangées sur un système Debian. Mentionnez cependant tout changement
+d'emplacement d'un fichier de configuration.
+ <p>
+Les seuls bogues fermés par une entrée de changelog devraient être ceux qui sont
+vraiment corrigés dans la même révision du paquet. Fermer des bogues non liés
+par le fichier changelog est considéré comme une très mauvaise pratique.
+Veuillez voir <ref id="upload-bugfix">.
+ <p>
+Les entrées de changelog <strong>ne devraient pas</strong> être le lieu de
+discussions avec les émetteurs de bogues (« Je ne vois pas de segfaults
+lors du lancement de foo avec l'option bar ; envoyez-moi plus
+d'informations. »), ni celui de phrases génériques sur la vie, l'univers et
+tout le reste (« Désolé, cet envoi m'a pris du temps, mais j'avais attrapé
+la grippe. ») ou celui de demandes d'aide (" La liste des bogues sur
+ce paquet est énorme, donnez-moi un coup de main. »). Ceci ne sera
+généralement pas remarqué par les personnes ciblées, mais peut ennuyer les
+personnes qui désirent lire des informations sur les changements réels du
+paquet. Veuillez vous reporter à <ref id="bug-answering"> pour plus
+d'informations sur la façon d'utiliser le système de suivi des bogues.
+ <p>
+C'est une vieille tradition de valider les bogues fixés par une mise à jour
+indépendante dans la première entrée du changelog de l'envoi du vrai
+responsable, par exemple, dans une entrée de changelog comme ceci :
+<example>
+ * Maintainer upload, closes: #42345, #44484, #42444.
+</example>
+Ceci fermera les bogues NMU marqués comme corrigé (« fixed ») quand le
+paquet arrivera dans l'archive. Le bogue pour le fait qu'une NMU a été faite
+peut être fermé de la même façon. Bien sûr, il est également parfaitement
+acceptable de fermer les bogues corrigés par NMU par d'autres moyens ; voir
+<ref id="bug-answering">.
+</sect1>
+
+ <sect1 id="bpp-changelog-errors">
+ <heading>Erreurs communes dans les entrées de changelogs</heading>
+<p>
+Les exemples suivants montrent des erreurs communes ou des exemples de mauvais
+style dans les entrées de changelog<footnote>NdT : Les entrées de
+changelog sont ici affichées en français pour faciliter la compréhension, mais
+vos entrées devront naturellement être rédigées en anglais.</footnote>.
+
+<p>
+<example>
+ * Corrige tous les bogues restants.
+</example>
+<p>
+Ceci n'indique visiblement rien d'utile au lecteur.
+<p>
+<example>
+ * Correctif de Jane Random appliqué.
+</example>
+Sur quoi portait le correctif ?
+
+<p>
+<example>
+ * Révision de cible d'installation la nuit dernière.
+</example>
+Révision qui a accompli quoi ? Est-ce que la mention de la nuit dernière
+est supposée nous rappeler que nous ne devons pas faire confiance à ce
+code ?
+
+<p>
+<example>
+ * Corrige MRD vsync av. anciens CRTs.
+</example>
+Trop d'acronymes et il n'est pas très clair de ce qu'était vraiment cette...
+ euh..., merde (oups, un mot interdit !) ou comment cela a été corrigé.
+
+<p>
+<example>
+ * Ceci n'est pas un bogue. Closes: #nnnnnn.
+</example>
+Premièrement, il n'y a absolument pas besoin d'envoyer un paquet pour
+communiquer cette information ; à la place, utilisez le système de suivi des
+bogues. Deuxièmement, il n'y a aucune explication concernant la raison
+pour laquelle le rapport n'était pas un bogue.
+
+<p>
+<example>
+ * A été fixé il y a longtemps, mais j'ai oublié de le fermer. Closes: #54321.
+</example>
+Si, pour toute raison, vous n'aviez pas indiqué le numéro du bogue dans une
+précédente entrée de changelog, ceci n'est pas un problème, fermez simplement le
+bogue normalement dans le BTS. Il n'y a pas besoin de modifier le fichier
+changelog, en supposant que la description de la correction est déjà intégrée
+(ceci s'applique aux correctifs par les auteurs/responsables amonts également,
+vous n'avez pas à suivre les bogues qui ont été corrigés il y a longtemps dans
+votre changelog).
+
+<p> <!-- MANQUE UN . final -->
+<example>
+ * Closes: #12345, #12346, #15432
+</example>
+Où est la description ?! Si vous n'arrivez pas à trouver un message
+descriptif, commencez par insérer le titre de chacun des différents bogues.
+<p>
+</sect1>
+</sect>
+
+<!-- <sect1 id="pkg-mgmt-cvs">Managing a package with CVS
+ <p>
+ &FIXME; presentation of cvs-buildpackage, updating sources
+ via CVS (debian/rules refresh).
+ <url id="http://www.debian.org/devel/cvs_packages">
+-->
+