chiark / gitweb /
- Documented how to add custom content to the PTS.
[developers-reference.git] / developers-reference.sgml
index d8155a7080f2b419f0de653e85a11d06436f5c68..ea0d883fe903f319eab9ed2a89aed08477b49e46 100644 (file)
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.184 $">
+  <!entity cvs-rev "$Revision: 1.199 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
   <book>
       <title>Debian Developer's Reference
 
-      <author>Adam Di Carlo, current maintainer <email>aph@debian.org</email>
-      <author>Raphaël Hertzog, co-maintainer <email>hertzog@debian.org</email>
-      <author>Christian Schwarz <email>schwarz@debian.org</email>
-      <author>Ian Jackson <email>ijackson@gnu.ai.mit.edu</email>
+      <author>Developer's Reference Team &email-devel-ref;
+      <author>Adam Di Carlo, editor
+      <author>Raphaël Hertzog
+      <author>Christian Schwarz
+      <author>Ian Jackson
       <version>ver. &version;, &date-en;
 
       <copyright>
        <copyrightsummary>
 copyright &copy; 1998&mdash;2003 Adam Di Carlo</copyrightsummary>
        <copyrightsummary>
-copyright &copy; 2002 Raphaël Hertzog</copyrightsummary>
+copyright &copy; 2002&mdash;2003 Raphaël Hertzog</copyrightsummary>
        <copyrightsummary>
 copyright &copy; 1997, 1998 Christian Schwarz</copyrightsummary>
        <p>
@@ -335,8 +336,8 @@ know that you're unavailable.
 In order to inform the other developers, there's two things that you should do.
 First send a mail to &email-debian-private; with "[VAC] " prepended to the
 subject of your message<footnote>This is so that the message can be easily
-filtered by people who don't want to read vacation notices.</footnote>,
-giving the period of time when you will be on vacation. You can also give
+filtered by people who don't want to read vacation notices.</footnote>
+and state the period of time when you will be on vacation. You can also give
 some special instructions on what to do if a problem occurs.
        <p>
 The other thing to do is to mark yourself as "on vacation" in the
@@ -470,8 +471,10 @@ it to see the responses.
 Cross-posting (sending the same message to multiple lists) is discouraged.
 As ever on the net, please trim down the quoting of articles you're
 replying to.  In general, please adhere to the usual conventions for
-posting messages. Please read the <url name="code of conduct"
-id="&url-debian-lists;"> for more information.
+posting messages.
+       <p>
+Please read the <url name="code of conduct" id="&url-debian-lists;">
+for more information.
 
        <sect1 id="mailing-lists-special">Special lists
        <p>
@@ -924,7 +927,7 @@ Note that development under <em>unstable</em> continues during the
 freeze period, since the <em>unstable</em> distribution remains in
 place in parallel with <em>testing</em>.
 
-       <sect2>Experimental
+       <sect2 id="experimental">Experimental
          <p>
 The <em>experimental</em> distribution is a special distribution.
 It is not a full distribution in the same sense as `stable' and
@@ -937,6 +940,13 @@ packages from <em>experimental</em> are expected to have been duly
 warned.  In short, all bets are off for the <em>experimental</em>
 distribution.
          <p>
+These are the <manref name="sources.list" section="5"> lines for
+<em>experimental</em>:
+<example>
+deb http://ftp.<var>xy</var>.debian.org/debian/ ../project/experimental main
+deb-src http://ftp.<var>xy</var>.debian.org/debian/ ../project/experimental main
+</example>
+         <p>
 If there is a chance that the software could do grave damage to a system,
 it is likely to be better to put it into <em>experimental</em>.
 For instance, an experimental compressed file system should probably go
@@ -1239,7 +1249,11 @@ override disparity for the section or priority field).
     <tag><tt>default</tt>
     <item>
 Any non-automatic mail sent to the PTS by people who wanted to
-contact the subscribers of the package.
+contact the subscribers of the package. This can be done by sending mail
+to <tt><var>srcpackage</var>@&pts-host;</tt>. In order to prevent spam,
+mails sent to these addresses must contain the header "X-PTS-Approved"
+with a non-empty string.
+
 
     <tag><tt>summary</tt>
     <item>
@@ -1364,6 +1378,86 @@ notifications, you just have to make sure it sends a copy of those mails
 to <tt><var>srcpackage</var>_cvs@&pts-host;</tt>. Only people who
 accepts the <em>cvs</em> keyword will receive the notifications.
 
+       <sect1 id="pts-web">The PTS web interface
+       <p>
+The PTS has been extended with a web interface that puts together
+many information about each source package. It features many useful
+links (BTS, QA stats, contact information, DDTP translation status,
+buildd logs) and gathers many more information from various places
+(30 latest changelog entries, testing status, ...). It's a very useful
+tool if you want to know what's going on with a specific source
+package. Furthermore there's a form that let you easily subscribe to
+the mail service offered by the PTS.
+       <p>
+You can jump directly to the web page concerning a specific source package
+with an url like <tt>http://&pts-host;/<var>srcpackage</var></tt>. Otherwise
+you can go through the <url id="http://&pts-host;" name="main page">.
+       <p>
+This web interface has been designed like a portal for the development of
+packages: you can add custom content on the pages of your packages. You can
+add "static information" (news item that are meant to stay available
+indefinitely) and news items in the "latest news" section.
+       <p>
+Static news can be used to indicate:
+<list>
+<item>the availability of a project hosted on alioth.debian.org for co-maintaining the package
+<item>a link to the upstream website
+<item>a link to the upstream bugtracker
+<item>the existence of an IRC channel dedicated to the software
+<item>any other available resource that could be useful in the maintenance of the package
+</list>
+Usual news item may be used to announce that:
+<list>
+<item>beta packages are available for test
+<item>final packages are expected for next week
+<item>the packaging is about to be redone from scratch
+<item>backports are available
+<item>the maintainer is on vacation (if he wishes to publish this information)
+<item>a NMU is being worked on
+<item>something important will affect the package
+</list>
+       <p>
+Both kind of news are generated in a similar manner: you just have to send a mail
+either to <email>pts-static-news@qa.debian.org</email> or to
+<email>pts-news@qa.debian.org</email>. The mail should indicate which package is
+concerned by the news by giving the name of the source package in a
+<tt>X-PTS-Package</tt> mail header or in a <tt>Package</tt> pseudo-header (like the
+BTS reports). If an URL is available in the <tt>X-PTS-Url</tt> mail header or in
+the <tt>Url</tt> pseudo-header, then the result is a link to that URL instead
+of a complete news item.
+       <p>
+Some examples of valid mails used to generate news item in the PTS are following. The first one
+adds a link to the cvsweb interface of debian-cd in the "Static information" section.
+<example>
+From: Raphael Hertzog &lt;hertzog@debian.org&gt;
+To: pts-static-news@qa.debian.org
+Subject: Browse debian-cd CVS repository with cvsweb
+
+Package: debian-cd
+Url: http://cvs.debian.org/debian-cd/
+</example>
+The second one is an announce sent to a mailing list which is also sent
+to the PTS so that it is published on the PTS web page of the package. Note the
+use of the BCC field to avoid answers sent to the PTS by mistake ...
+<example>
+From: Raphael Hertzog &lt;hertzog@debian.org&gt;
+To: debian-gtk-gnome@lists.debian.org
+Bcc: pts-news@qa.debian.org
+Subject: Galeon 2.0 backported for woody
+X-PTS-Package: galeon
+
+Hello gnomers !
+
+I'm glad to announce that galeon has been backported for woody. You'll find
+everything here:
+...
+</example>
+       <p>
+Think twice before adding a news to the PTS because you won't be able to
+remove it later and you wan't be able to edit it either. The only thing that you
+can do is send a second news that will deprecate the information contained in
+the first news.
+
     <sect id="ddpo">Developer's packages overview
        <p>
 A QA (quality assurance) web portal is available at <url
@@ -1566,7 +1660,7 @@ It is technically possible to upload a package into several distributions
 at the same time but it usually doesn't make sense to use that feature
 because the dependencies of the package may vary with the distribution.
 In particular, it never makes sense to combine the <em>experimental</em>
-distribution with anything else.
+distribution with anything else (see <ref id="experimental">).
 
        <sect1 id="upload-stable">Uploads to <em>stable</em>
          <p>
@@ -1829,13 +1923,23 @@ according to their licensing, e.g. <em>main</em>, <em>contrib</em> and
 <em>non-free</em>. This is described in another section, <ref id="archive">.
 
 
-    <sect id="bug-handling">Handling package bugs
+    <sect id="bug-handling">Handling bugs
+       <p>
+Every developer has to be able to work with the Debian <url name="bug
+tracking system" id="&url-bts;">. This includes knowing how to file bug
+reports properly (see <ref id="submit-bug">), how to update them and
+reorder them, and how to process and close them.
+       <p>
+The bug tracking system's features interesting to developers are described
+in the <url id="&url-bts-devel;" name="BTS documentation for developers">.
+This includes closing bugs, sending followup messages, assigning severities,
+tags, marking bugs as forwarded and other issues.
        <p>
-Often as a package maintainer, you find bugs in other packages or else
-have bugs reported to your packages which need to be reassigned.  The
-<url id="&url-bts-control;" name="BTS instructions"> can tell you how
-to do this.  Some information on filing bugs can be found in <ref
-id="submit-bug">.
+Operations such as reassigning bugs to other packages, merging separate
+bug reports about the same issue, or reopening bugs when they are
+prematurely closed, are handled using the so-called control mail server.
+All of the commands available in this server are described in the
+<url id="&url-bts-control;" name="BTS control server documentation">.
 
       <sect1 id="bug-monitoring">Monitoring bugs
        <p>
@@ -3066,22 +3170,22 @@ documentation and examples (in <file>/usr/share/doc/dpatch</file>).
        <sect1 id="multiple-binary">Multiple binary packages
        <p>
 A single source package will often build several binary packages,
-either to provide several flavors of the same software (examples are
-the <package>vim-*</package> packages) or to make several small
+either to provide several flavors of the same software (e.g.,
+the <package>vim</package> source package) or to make several small
 packages instead of a big one (e.g., if the user can install only the
 subset she needs, and thus save some disk space).
        <p>
 The second case can be easily managed in <file>debian/rules</file>.
 You just need to move the appropriate files from the build directory
 into the package's temporary trees.  You can do this using
-<prgn>install</prgn> (vanilla approach) or <prgn>dh_install</prgn>
-(from <package>debhelper</package>).  Be sure to check the different
+<prgn>install</prgn> or <prgn>dh_install</prgn>
+from <package>debhelper</package>.  Be sure to check the different
 permutations of the various packages, ensuring that you have the
 inter-package dependencies set right in <file>debian/control</file>.
        <p>
 The first case is a bit more difficult since it involves multiple
-recompiles of the same software but with different configure
-options. The <package>vim</package> is an example of how to manage
+recompiles of the same software but with different configuration
+options. The <package>vim</package> source package is an example of how to manage
 this using an hand-crafted <file>debian/rules</file> file.
 
 <!-- &FIXME; Find a good debhelper example with multiple configure/make
@@ -3089,102 +3193,125 @@ this using an hand-crafted <file>debian/rules</file> file.
         </sect1>
       </sect>
 
-    <sect id="bpp-debian-maint-scripts">
-        <heading>Best practices for maintainer scripts</heading>
-        <p>
-Maintainer scripts include the files <file>debian/postinst</file>,
-<file>debian/preinst</file>, <file>debian/prerm</file> and
-<file>debian/postrm</file>.  These scripts take care of any package
-installation or deinstallation setup which isn't handled merely by the
-creation or removal of files and directories.  The following
-instructions supplement the <url id="&url-debian-policy;" name="Debian
-Policy">.
-        <p>
-Maintainer scripts must be idempotent.  That means that you need to
-make sure nothing bad will happen if the script is called twice where
-it would usually be called once.
-        <p>
-Standard input and output may be redirected (e.g. into pipes) for
-logging purposes, so don't rely on them being a tty.
-        <p>
-All prompting or interactive configuration should be kept to a
-minimum.  When it is necessary, you should use the
-<package>debconf</package> package for the interface.  Remember that
-prompting in any case can only be in the <tt>configure</tt> stage of
-the <file>postinst</file> script.
-        <p>
-Keep the maintainer scripts as simple as possible.  We suggest you use
-pure POSIX shell scripts.  Remember, if you do need any bash features,
-the maintainer script must have a bash sh-bang line.  POSIX shell or
-Bash are preferred to Perl, since they enable
-<package>debhelper</package> to easily add bits to the scripts.
+
+      <sect id="bpp-debian-control">
+       <heading>Best practices for <file>debian/control</file></heading>
         <p>
-If you change your maintainer scripts, be sure to test package
-removal, double installation, and purging.  Be sure that a purged
-package is completely gone, that is, it must remove any files created,
-directly or indirectly, in any maintainer script.
+The following practices are relevant to the
+<file>debian/control</file> file.  They supplement the <url
+id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
+name="Policy on package descriptions">.
         <p>
-If you need to check for the existence of a command, you should use
-something like
-<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
+The description of the package, as defined by the corresponding field
+in the <file>control</file> file, contains both the package synopsis
+and the long description for the package.  <ref id="bpp-desc-basics">
+describes common guidelines for both parts of the package description.
+Following that, <ref id="bpp-pkg-synopsis"> provides guidelines
+specific to the synopsis, and <ref id="bpp-pkg-desc"> contains
+guidelines specific to the description.
+
+       <sect1 id="bpp-desc-basics">
+          <heading>General guidelines for package descriptions</heading>
+          <p>
+The package description should be written for the average likely user,
+the average person who will use and benefit from the package.  For
+instance, development packages are for developers, and can be
+technical in their language.  More general-purpose applications, such
+as editors, should be written for a less technical user.
+          <p>
+Our review of package descriptions lead us to conclude that most
+package descriptions are technical, that is, are not written to make
+sense for non-technical users.  Unless your package really is only for
+technical users, this is a problem.
+          <p>
+How do you write for non-technical users?  Avoid jargon.  Avoid
+referring to other applications or frameworks that the user might not
+be familiar with &mdash; "GNOME" or "KDE" is fine, since users are
+probably familiar with these terms, but "GTK+" is
+probably not.  Try not to assume any knowledge at all.  If you must
+use technical terms, introduce them.
+           <p>
+Be objective.  Package descriptions are not the place for advocating
+your package, no matter how much you love it.  Remember that the
+reader may not care about the same things you care about.
+          <p>
+References to the names of any other software packages, protocol names,
+standards, or specifications should use their canonical forms, if one
+exists.  For example, use "X Window System", "X11", or "X"; not "X
+Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk".
+Use "GNOME", not "Gnome".  Use "PostScript", not "Postscript" or
+"postscript".
+          <p>
+If you are having problems writing your description, you may wish to
+send it along to &email-debian-l10n-english; and request feedback.
+        </sect1>
 
-If you don't wish to hard-code the path of the command in your
-maintainer script, the following POSIX-compliant shell function may
-help:
 
-&example-pathfind;
+       <sect1 id="bpp-pkg-synopsis">
+          <heading>The package synopsis, or short description</heading>
+           <p>
+The synopsis line (the short description) should be concise.  It
+must not repeat the package's name (this is policy).
+           <p>
+It's a good idea to think of the synopsis as an appositive clause, not
+a full sentence.  An appositive clause is defined in WordNet as a
+grammatical relation between a word and a noun phrase that follows,
+e.g., "Rudolph the red-nosed reindeer".  The appositive clause here is
+"red-nosed reindeer".  Since the synopsis is a clause, rather than a
+full sentence, we recommend that it neither start with a capital nor
+end with a full stop (period).  It should also not begin with an
+article, either definite ("the") or indefinite ("a" or "an").
+           <p>
+It might help to imagine that the synopsis is combined with the
+package name in the following way:
 
-You can use this function to search <tt>$PATH</tt> for a command name,
-passed as an argument.  It returns true (zero) if the command was
-found, and false if not.  This is really the most portable way, since
-<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
-POSIX.
-       <p>
-While <prgn>which</prgn> is an acceptable alternative, since
-it is from the required <package>debianutils</package> package, it's
-not on the root partition. That is, it's in <file>/usr/bin</file> rather
-than <file>/bin</file>, so one can't use it in scripts which are run
-before the <file>/usr</file> partition is mounted. Most scripts won't have
-this problem, though.
+<example><var>package-name</var> is a <var>synopsis</var>.</example>
 
+Alternatively, it might make sense to think of it as
 
-    <sect id="bpp-debian-control">
-       <heading>Best practices for <file>debian/control</file></heading>
-        <p>
-The following practices supplement the <url
-            id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
-            name="Policy on package descriptions">.</p>
+<example><var>package-name</var> is <var>synopsis</var>.</example>
+
+or, if the package name itself is a plural (such as
+"developers-tools")
+
+<example><var>package-name</var> are <var>synopsis</var>.</example>
+
+This way of forming a sentance from the package name and synopsis
+should be considered as a heuristic and not a strict rule.  There are
+some cases where it doesn't make sense to try to form a sentance.
+        </sect1>
 
        <sect1 id="bpp-pkg-desc">
-           <heading>Writing useful descriptions</heading>
+          <heading>The long description</heading>
            <p>
-The description of the package (as defined by the corresponding field
-in the <file>control</file> file) is the primary information available
-to the user about a package before they install it.  It should provide
-all the required information to let the user decide whether to install
-the package.
+The long description is the primary information available to the user
+about a package before they install it.  It should provide all the
+information needed to let the user decide whether to install the
+package.  Assume that the user has already read the package synopsis.
            <p>
-The following practices supplement the <url name="Policy on the descriptions
-of packages" id="&url-debian-policy;ch-miscellaneous.html#s-descriptions">.
+The long description should consist of full and complete sentences.
            <p>
-The synopsis line (the short description) should primarily be concise.
-You may capitalize the first letter for aesthetics. It is customary to
-make the synopsis an appositive clause (not a full sentence) in which
-case there's no need to put a full stop (period) at the end.
+The first paragraph of the long description should answer the
+following questions: what does the package do?  what task does it help
+the user accomplish?  It is important to describe this in a
+non-technical way, unless of course the audience for the package is
+necessarily technical.
            <p>
-The long description should, however, always consist of full sentences.
+The following paragraphs should answer the following questions: Why do
+I as a user need this package?  What other features does the package
+have?  What outstanding features and deficiencies are there compared
+to other packages (e.g., "if you need X, use Y instead")?  Is this
+package related to other packages in some way that is not handled by
+the package manager (e.g., "this is the client to the foo server")?
            <p>
-Since the first user impression is based on the description, be
-careful to avoid spelling and grammar mistakes. Ensure that you
+Be careful to avoid spelling and grammar mistakes. Ensure that you
 spell-check it.  <prgn>ispell</prgn> has a special <tt>-g</tt> option
 for <file>debian/control</file> files:
 
 <example>ispell -d american -g debian/control</example>
-
-If you want someone to proofread the description that you
-intend to use you may ask on &email-debian-l10n-english;.
         </sect1>
 
+
         <sect1 id="bpp-upstream-info">
           <heading>Upstream home page</heading>
           <p>
@@ -3201,7 +3328,7 @@ correctly.  To see an example of how this displays, see <url
 id="&url-eg-desc-upstream-info;">.
           <p>
 If there is no home page for the software, this should naturally be
-left empty.
+left out.
           <p>
 Note that we expect this field will eventually be replaced by a proper
 <file>debian/control</file> field understood by <prgn>dpkg</prgn> and
@@ -3283,16 +3410,10 @@ for instance, in a changelog entry like this:
 <example>
   * Maintainer upload, closes: #42345, #44484, #42444.
 </example>
-This will close the NMU bugs in "fixed" state when the package makes
-it into the archive (and also the bug for the fact that an NMU was
-done).  It is also perfectly acceptable to close NMU-fixed bugs by
-other means; see <ref id="bug-answering">.
-       <p>
-Changelogs shouldn't include general statements on life, the universe
-and everything ("sorry this upload took me so long, but I caught the
-flu").  Exceptions can be made if the comment is funny ;-) Obviously,
-this is subjective, so it's likely best if it's kept out of technical
-documentation such as changelogs.
+This will close the NMU bugs tagged "fixed" when the package makes
+it into the archive. The bug for the fact that an NMU was done can be
+closed the same way. Of course, it's also perfectly acceptable to
+close NMU-fixed bugs by other means; see <ref id="bug-answering">.
         </sect1>
 
        <sect1 id="bpp-changelog-errors">
@@ -3360,12 +3481,72 @@ start by inserting the title of each different bug.
        <p>
        &FIXME; presentation of cvs-buildpackage, updating sources
        via CVS (debian/rules refresh).
+       <url id="http://www.debian.org/devel/cvs_packages">
 -->
 
 
+      <sect id="bpp-debian-maint-scripts">
+        <heading>Best practices for maintainer scripts</heading>
+        <p>
+Maintainer scripts include the files <file>debian/postinst</file>,
+<file>debian/preinst</file>, <file>debian/prerm</file> and
+<file>debian/postrm</file>.  These scripts take care of any package
+installation or deinstallation setup which isn't handled merely by the
+creation or removal of files and directories.  The following
+instructions supplement the <url id="&url-debian-policy;" name="Debian
+Policy">.
+        <p>
+Maintainer scripts must be idempotent.  That means that you need to
+make sure nothing bad will happen if the script is called twice where
+it would usually be called once.
+        <p>
+Standard input and output may be redirected (e.g. into pipes) for
+logging purposes, so don't rely on them being a tty.
+        <p>
+All prompting or interactive configuration should be kept to a
+minimum.  When it is necessary, you should use the
+<package>debconf</package> package for the interface.  Remember that
+prompting in any case can only be in the <tt>configure</tt> stage of
+the <file>postinst</file> script.
+        <p>
+Keep the maintainer scripts as simple as possible.  We suggest you use
+pure POSIX shell scripts.  Remember, if you do need any bash features,
+the maintainer script must have a bash sh-bang line.  POSIX shell or
+Bash are preferred to Perl, since they enable
+<package>debhelper</package> to easily add bits to the scripts.
+        <p>
+If you change your maintainer scripts, be sure to test package
+removal, double installation, and purging.  Be sure that a purged
+package is completely gone, that is, it must remove any files created,
+directly or indirectly, in any maintainer script.
+        <p>
+If you need to check for the existence of a command, you should use
+something like
+<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
+
+If you don't wish to hard-code the path of the command in your
+maintainer script, the following POSIX-compliant shell function may
+help:
+
+&example-pathfind;
+
+You can use this function to search <tt>$PATH</tt> for a command name,
+passed as an argument.  It returns true (zero) if the command was
+found, and false if not.  This is really the most portable way, since
+<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
+POSIX.
+       <p>
+While <prgn>which</prgn> is an acceptable alternative, since
+it is from the required <package>debianutils</package> package, it's
+not on the root partition. That is, it's in <file>/usr/bin</file> rather
+than <file>/bin</file>, so one can't use it in scripts which are run
+before the <file>/usr</file> partition is mounted. Most scripts won't have
+this problem, though.
+      </sect>
+
+
       <sect id="bpp-config-mgmt">
        <heading>Configuration management with <package>debconf</package></heading>
-       
        <p>
 <package>Debconf</package> is a configuration management system which
 can be used by all the various packaging scripts
@@ -3559,9 +3740,9 @@ this data is negligible compared to the size of the rest of the
 package, it's probably best to keep it all in a single package.
           <p>
 However, if the size of the data is considerable, consider splitting
-it out into a separate, architecture-independent package.
-("_all.deb").  By doing this, you avoid needless duplication of the
-same data into eleven or more .debs per each architecture.  While this
+it out into a separate, architecture-independent package ("_all.deb").
+By doing this, you avoid needless duplication of the same data into
+eleven or more .debs, one per each architecture.  While this
 adds some extra overhead into the <file>Packages</file> files, it
 saves a lot of disk space on Debian mirrors.  Separating out
 architecture-independent data also reduces processing time of
@@ -3586,21 +3767,39 @@ members in choosing what they want to work on and in choosing
 the most critical thing to spend their time on.
 
     <sect id="submit-bug">
-        <heading>Bug reporting</heading>
+      <heading>Bug reporting</heading>
         <p>
 We encourage you to file bugs as you find them in Debian packages.  In
 fact, Debian developers are often the first line testers.  Finding and
-reporting bugs in other developer's packages improves the quality of
+reporting bugs in other developers' packages improves the quality of
 Debian.
        <p>
+Read the <url name="instructions for reporting bugs"
+id="&url-bts-report;"> in the Debian <url name="bug tracking system"
+id="&url-bts;">.
+       <p>
 Try to submit the bug from a normal user account at which you are
-likely to receive mail.  Do not submit bugs as root.
+likely to receive mail, so that people can reach you if they need
+further information about the bug.  Do not submit bugs as root.
+       <p>
+You can use a tool like <manref name="reportbug" section="1"> to
+submit bugs. It can automate and generally ease the process.
+       <p>
+Make sure the bug is not already filed against a package.
+Each package has a bug list easily reachable at
+<tt>http://&bugs-host;/<var>packagename</var></tt>
+Utilities like <manref name="querybts" section="1"> can also
+provide you with this information (and <prgn>reportbug</prgn>
+will usually invoke <prgn>querybts</prgn> before sending, too).
+       <p>
+Try to direct your bugs to the proper location. When for example
+your bug is about a package that overwrites files from another package,
+check the bug lists for <em>both</em> of those packages in order to
+avoid filing duplicate bug reports.
        <p>
-Make sure the bug is not already filed against a package.  Try to do a
-good job reporting a bug and redirecting it to the proper location.
 For extra credit, you can go through other packages, merging bugs
-which are reported more than once, or setting bug severities to
-`fixed' when they have already been fixed.  Note that when you are
+which are reported more than once, or tagging bugs `fixed'
+when they have already been fixed.  Note that when you are
 neither the bug submitter nor the package maintainer, you should
 not actually close the bug (unless you secure permission from the
 maintainer).
@@ -3609,7 +3808,7 @@ From time to time you may want to check what has been going on
 with the bug reports that you submitted. Take this opportunity to
 close those that you can't reproduce anymore. To find
 out all the bugs you submitted, you just have to visit
-<tt>http://&bugs-host;/from:&lt;your-email-addr&gt;</tt>.
+<tt>http://&bugs-host;/from:<var>&lt;your-email-addr&gt;</var></tt>.
 
       <sect1 id="submit-many-bugs">Reporting lots of bugs at once
        <p>
@@ -4317,6 +4516,9 @@ it.</p>
 <!-- FIXME: add the following
 
 questionable:
+  dbs (referred to above)
+  dpatch (referred to above)
+  debarchiver
   ucf
   dpkg-awk
   grep-dctrl