<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.191 $">
+ <!entity cvs-rev "$Revision: 1.197 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
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>
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
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
recompiled on most of the architectures.
<sect id="pkg-tracking-system">The Package Tracking System
+<!-- FIXME: talk about
+http://qa.debian.org/developer.php?login=aph@debian.org
+http://packages.qa.debian.org/
+http://packages.qa.debian.org/pkgname -->
<p>
The Package Tracking System (PTS) is basically a tool to track by mail
the activity of a source package. You just have to subscribe
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>
<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>
-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">.
+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>
+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>
<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
<p>
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.
-
+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>
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). Imagine that the synopsis is combined
-with the package name in the following way:
+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:
-<example>The <var>package-name</var> is a <var>synopsis</var>.</example>
+<example><var>package-name</var> is a <var>synopsis</var>.</example>
+
+Alternatively, it might make sense to think of it as
+
+<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">
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).
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:<your-email-addr></tt>.
+<tt>http://&bugs-host;/from:<var><your-email-addr></var></tt>.
<sect1 id="submit-many-bugs">Reporting lots of bugs at once
<p>
<!-- FIXME: add the following
questionable:
+ dbs (referred to above)
+ dpatch (referred to above)
+ debarchiver
ucf
dpkg-awk
grep-dctrl