<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
<!-- include version information so we don't have to hard code it
within the document -->
- <!entity % versiondata SYSTEM "version.ent"> %versiondata;
+ <!ENTITY % versiondata SYSTEM "version.ent"> %versiondata;
<!-- common, language independant entities -->
- <!entity % commondata SYSTEM "common.ent" > %commondata;
+ <!ENTITY % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.178 $">
+ <!ENTITY cvs-rev "$Revision: 1.216 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
- <!entity cvs-en-rev "X.YY">
+ <!ENTITY cvs-en-rev "X.YY">
-->
- <!-- -->
- <!entity FIXME "<em>FIXME:</em> ">
+ <!-- how to mark a section that needs more work -->
+ <!ENTITY FIXME "<em>FIXME:</em> ">
]>
<debiandoc>
<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 © 1998—2003 Adam Di Carlo</copyrightsummary>
<copyrightsummary>
-copyright © 2002 Raphaël Hertzog</copyrightsummary>
+copyright © 2002—2003 Raphaël Hertzog</copyrightsummary>
<copyrightsummary>
copyright © 1997, 1998 Christian Schwarz</copyrightsummary>
<p>
<sect id="user-maint">Maintaining your Debian information
<p>
-There's a LDAP database containing information about all
-developers, you can access it at <url id="&url-debian-db;">. You can
-update your password (this password is propagated to most of the machines
-that are accessible to you), your address, your country, the latitude and
-longitude of the point where you live, phone and fax numbers, your
-preferred shell, your IRC nickname, your web page and the email that
-you're using as alias for your debian.org email. Most of the information
-is not accessible to the public, for more details about this
-database, please read its online documentation that you can find
-at <url id="&url-debian-db-doc;">.
+There's a LDAP database containing information about Debian developers at
+<url id="&url-debian-db;">. You should enter your information there and
+update it as it changes. Most notably, make sure that the address where your
+debian.org email gets forwarded to is always up to date, as well as the
+address where you get your debian-private subscription if you choose to
+subscribe there.
<p>
-You have to keep the information available there up-to-date.
+For more information about the database, please see <ref id="devel-db">.
+
+
<sect id="key-maint">Maintaining your public key
<p>
<url id="&url-vote;" name="Debian Voting Information"> page, along with
information on how to make, second and vote on proposals.
+
<sect id="inform-vacation">Going on vacation gracefully
<p>
-Most developers take vacations, and usually this means that they can't
-work for Debian and they can't be reached by email if any problem occurs.
-The other developers need to know that you're on vacation so that they'll
-do whatever is needed when such a problem occurs. Usually this means that
-other developers are allowed to NMU (see <ref id="nmu">) your package if a
-big problem (release critical bugs, security update, etc.) occurs while
-you're on vacation.
+It is common for developers to have periods of absence, whether those are
+planned vacations or simply being buried in other work. The important thing
+to notice is that the other developers need to know that you're on vacation
+so that they can do whatever is needed if a problem occurs with your
+packages or other duties in the project.
+ <p>
+Usually this means that other developers are allowed to NMU (see
+<ref id="nmu">) your package if a big problem (release critical bugs,
+security update, etc.) occurs while you're on vacation. Sometimes it's
+nothing as critical as that, but it's still appropriate to let the others
+know that you're unavailable.
<p>
In order to inform the other developers, there's two things that you should do.
-First send a mail to &email-debian-private; giving the period of time when
-you will be on vacation. You can also give some special instructions on what to
-do if any problem occurs. Be aware that some people don't care for vacation
-notices and don't want to read them; you should prepend "[VAC] " to the
-subject of your message so that it can be easily filtered.
+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>
+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>
-Next you should update your information
-available in the Debian LDAP database and mark yourself as ``on vacation''
-(this information is only accessible to debian developers). Don't forget
-to remove the ``on vacation'' flag when you come back!
+The other thing to do is to mark yourself as "on vacation" in the
+<qref id="devel-db">Debian developers' LDAP database</qref> (this
+information is only accessible to Debian developers).
+Don't forget to remove the "on vacation" flag when you come back!
+
<sect id="upstream-coordination">Coordination with upstream developers
<p>
A big part of your job as Debian maintainer will be to stay in contact
with the upstream developers. Debian users will sometimes report bugs
-to the Bug Tracking System that are not specific to Debian. You
-must forward these bug reports to the upstream developers so that
-they can be fixed in a future release. It's not your job to fix
-non-Debian specific bugs. However, if you are able to do so, you are
-encouraged to contribute to upstream development of the package by
-providing a fix for the bug. Debian users and developers will often
-submit patches to fix upstream bugs, and you should evaluate and
-forward these patches upstream.
+that are not specific to Debian to our bug tracking system. You
+have to forward these bug reports to the upstream developers so that
+they can be fixed in a future upstream release.
+ <p>
+While it's not your job to fix non-Debian specific bugs, you may freely
+do so if you're able. When you make such fixes, be sure to pass them on
+to the upstream maintainers as well. Debian users and developers will
+sometimes submit patches to fix upstream bugs -- you should evaluate
+and forward these patches upstream.
<p>
If you need to modify the upstream sources in order to build a policy
compliant package, then you should propose a nice fix to the upstream
modify the sources of the next upstream version. Whatever changes you
need, always try not to fork from the upstream sources.
+
<sect id="rc-bugs">Managing release-critical bugs
<p>
Generally you should deal with bug reports on your packages as described in
<sect id="mailing-lists">Mailing lists
<p>
-The mailing list server is at <tt>&lists-host;</tt>.
+Much of the conversation between Debian developers (and users) is managed
+through a wide array of mailing lists we host at
+<tt><url id="http://&lists-host;/" name="&lists-host;"></tt>.
+To find out more on how to subscribe or unsubscribe, how to post and how not
+to post, where to find old posts and how to search them, how to contact the
+list maintainers and see various other information about the mailing lists,
+please read <url id="&url-debian-lists;">. This section will only cover
+aspects of mailing lists that are of particular interest to developers.
+
+ <sect1 id="mailing-lists-rules">Basic rules for use
+ <p>
+When replying to messages on the mailing list, please do not send a
+carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
+request to be copied. Anyone who posts to a mailing list should read
+it to see the responses.
+ <p>
+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.
<p>
-Online archives of mailing lists are available at <url
-id="&url-lists-archives;">.
+Please read the <url name="code of conduct" id="&url-debian-lists;#codeofconduct">
+for more information.
<sect1 id="core-devel-mailing-lists">Core development mailing lists
<p>
</item>
</list>
<p>
-There are
-other mailing lists available for a variety of special topics; see
-<url id="&url-debian-lists-subscribe;"> for a list.
-
- <sect1 id="mailing-lists-subunsub">Subscribing and unsubscribing
- <p>
-To subscribe to or unsubscribe from any of the Debian mailing lists, email
-<tt>debian-<var>foo</var>-REQUEST@&lists-host;</tt>, where
-<tt>debian-<var>foo</var></tt> is the name of the list, with the word
-<tt>subscribe</tt> in the <em>Subject</em> to subscribe to the list or
-<tt>unsubscribe</tt> to unsubscribe.
- <p>
-If you prefer to use a web page to subscribe to multiple mailing lists,
-there's one at <url id="&url-debian-lists-subscribe;">.
- <p>
-You can download the current list of mailing lists and basic usage
-instructions from <url id="&url-debian-lists-txt;">
-or install the <package>doc-debian</package> package and have it
-locally in &file-mail-lists;.
-
- <sect1 id="mailing-lists-rules">Basic rules for use
- <p>
-When replying to messages on the mailing list, please do not send a
-carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
-request to be copied. Anyone who posts to a mailing list should read
-it to see the responses.
- <p>
-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.
+There are other mailing lists available for a variety of special topics;
+see <url id="http://&lists-host;/"> for a list.
<sect1 id="mailing-lists-special">Special lists
<p>
about licenses, bugs, etc. or discussing the project with others where it
might be useful to have the discussion archived somewhere.
+ <sect1 id="mailing-lists-new">Requesting new development-related lists
+ <p>
+Before requesting a mailing list that relates to the development of a
+package (or a small group of related packages), please consider if using
+an alias (via a .forward-aliasname file on master.debian.org, which
+translates into a reasonably nice <var>you-aliasname@debian.org</var>
+address) or a self-managed mailing list on <qref id="alioth">Alioth</qref>
+is more appropriate.
+ <p>
+If you decide that a regular mailing list on lists.debian.org is really what
+you want, go ahead and fill in a request, following <url name="the HOWTO"
+id="&url-debian-lists-new;">.
<sect id="irc-channels">IRC channels
<p>
<sect1 id="servers-bugs">The bugs server
<p>
-<tt>bugs.debian.org</tt> is the canonical location for the Bug Tracking
+<tt>&bugs-host;</tt> is the canonical location for the Bug Tracking
System (BTS). If you plan on doing some statistical analysis or
processing of Debian bugs, this would be the place to do it. Please
describe your plans on &email-debian-devel; before implementing
anything, however, to reduce unnecessary duplication of effort or
wasted processing time.
<p>
-All Debian developers have accounts on <tt>bugs.debian.org</tt>.
+All Debian developers have accounts on <tt>&bugs-host;</tt>.
<sect1 id="servers-ftp-master">The ftp-master server
<p>
the lack of hyphen between "non" and "us" in the pseudo-package name
— that's for backwards compatibility). Remember to check whether or
not someone else has already reported the problem on the
-<url id="http://bugs.debian.org/nonus.debian.org" name="Bug Tracking System">.
+<url id="http://&bugs-host;/nonus.debian.org" name="Bug Tracking System">.
<sect1 id="servers-www">The www-master server
<p>
submit a bug against the pseudo-package,
<package>www.debian.org</package>. Remember to check whether or not someone
else has already reported the problem on the
-<url id="http://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
+<url id="http://&bugs-host;/www.debian.org" name="Bug Tracking System">.
<sect1 id="servers-people">The people web server
<p>
<prgn>finger yourlogin@db.debian.org</prgn> to see what it reports.
<p>
Developers can <url name="log into the database" id="&url-debian-db-login;">
-to change their debian-private list subscription, their personal
-information, to mark themselves on vacation, etc.
-For more information on keeping your entry the developer database
-up-to-date, please see <ref id="user-maint">.
+to change various information about themselves, such as:
+<list>
+ <item>forwarding address for your debian.org email
+ <item>subscription to debian-private
+ <item>whether you are on vacation
+ <item>personal information such as your address, country,
+ the latitude and longitude of the place where you live
+ for use in <url name="the world map of Debian developers"
+ id="&url-worldmap;">, phone and fax numbers, IRC nickname
+ and web page
+ <item>password and preferred shell on Debian Project machines
+</list>
+ <p>
+Most of the information is not accessible to the public, naturally.
+For more information please read the online documentation that you can find
+at <url id="&url-debian-db-doc;">.
<p>
One can also submit their SSH keys to be used for authorization on the
official Debian machines, and even add new *.debian.net DNS entries.
the package (maintainer, version, etc.).
- <sect1>Distribution directories
+ <sect1>Distributions
<p>
The directory system described in the previous chapter is itself
contained within <em>distribution directories</em>. Each
freeze period, since the <em>unstable</em> distribution remains in
place in parallel with <em>testing</em>.
- <sect2>Experimental
+ <sect2 id="testing">
+ <heading>More information about the testing distribution</heading>
+ <p>
+The scripts that update the <em>testing</em> distribution are run each
+day after the installation of the updated packages. They generate the
+<file>Packages</file> files for the <em>testing</em> distribution, but
+they do so in an intelligent manner trying to avoid any inconsistency
+and trying to use only non-buggy packages.
+ <p>
+The inclusion of a package from <em>unstable</em> is conditional on
+the following:
+<list>
+ <item>
+The package must have been available in <em>unstable</em> for several days;
+the precise number depends on the upload's urgency field. It
+is 10 days for low urgency, 5 days for medium urgency and 2 days for high
+urgency. Those delays may be doubled during a freeze;
+ <item>
+It must have less release-critical bugs than the version available
+in <em>testing</em>;
+ <item>
+It must be available on all architectures on which it has been
+previously built. <ref id="madison"> may be of interest to
+check that information;
+ <item>
+It must not break any dependency of a package that is already available
+in <em>testing</em>;
+ <item>
+The packages on which it depends must either be available in <em>testing</em>
+or they must be accepted into <em>testing</em> at the same time (and they will
+if they respect themselves all the criteria);
+</list>
+ <p>
+To find out whether a package is progressing into testing or not, see the
+testing script output on the <url name="web page of the testing distribution"
+id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn>
+which is in the <package>devscripts</package> package. This utility can
+easily be used in a <manref name="crontab" section="5"> to keep one
+informed of the progression of their packages into <em>testing</em>.
+ <p>
+The <file>update_excuses</file> file does not always give the precise reason
+why the package is refused, one may have to find it on their own by looking
+what would break with the inclusion of the package. The <url
+id="&url-testing-maint;" name="testing web page"> gives some more information
+about the usual problems which may be causing such troubles.
+ <p>
+Sometimes, some packages never enter <em>testing</em> because the set of
+inter-relationship is too complicated and can not be sorted out
+by the scripts. In that case, the release manager must be
+contacted, and he will force the inclusion of the packages.
+ <p>
+In general, please refer to the <url name="testing web page"
+id="&url-testing-maint;"> for more information. It also includes
+answers to some of the frequently asked questions.
+
+
+ <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
<example>DELAY=5 dupload --to delayed <changes-file></example>
- <sect id="testing">
- <heading>The "testing" distribution</heading>
- <p>
-The scripts that update the <em>testing</em> distribution are run each day
-after the installation of the
-updated packages. They generate the <file>Packages</file> files for
-the <em>testing</em> distribution, but they do so in an intelligent manner
-trying to avoid any inconsistency and trying to use only
-non-buggy packages.
- <p>The inclusion of a package from <em>unstable</em> is conditional on the following:
-<list>
- <item>
-The package must have been available in <em>unstable</em> for several days;
-the precise number depends on the upload's urgency field. It
-is 10 days for low urgency, 5 days for medium urgency and 2 days for high
-urgency. Those delays may be doubled during a freeze;
- <item>
-It must have less release-critical bugs than the version available
-in <em>testing</em>;
- <item>
-It must be available on all architectures on which it has been
-previously built. <ref id="madison"> may be of interest to
-check that information;
- <item>
-It must not break any dependency of a package that is already available
-in <em>testing</em>;
- <item>
-The packages on which it depends must either be available in <em>testing</em>
-or they must be accepted into <em>testing</em> at the same time (and they will
-if they respect themselves all the criteria);
-</list>
- <p>
-To find out whether a package is progressing into testing or not, see the
-testing script output on the <url name="web page of the testing distribution"
-id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn>
-which is in the <package>devscripts</package> package. This utility can
-easily be used in a <manref name="crontab" section="5"> to keep one
-informed of the progression of their packages into <em>testing</em>.
- <p>
-The <file>update_excuses</file> file does not always give the precise reason
-why the package is refused, one may have to find it on their own by looking
-what would break with the inclusion of the package. The <url
-id="&url-testing-maint;" name="testing web page"> gives some more information
-about the usual problems which may be causing such troubles.
- <p>
-Sometimes, some packages never enter <em>testing</em> because the set of
-inter-relationship is too complicated and can not be sorted out
-by the scripts. In that case, the release manager must be
-contacted, and he will force the inclusion of the packages.
- <p>
-In general, please refer to the <url name="testing web page"
-id="&url-testing-maint;"> for more information. It also includes
-answers to some of the frequently asked questions.
-
<sect id="pkg-info">Package information
<p>
<sect id="pkg-tracking-system">The Package Tracking System
<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
-to a source package to start getting the mails related to it.
-You get the same mails as the maintainer. Each mail
-sent through the PTS is classified and associated to one of
-the keyword listed below. This will let you select the mails that
+The Package Tracking System (PTS) is an email-based tool to track
+the activity of a source package. This really means that you can
+get the same emails that the package maintainer gets, simply by
+subscribing to the package in the PTS.
+ <p>
+Each email sent through the PTS is classified and associated to one of
+the keywords listed below. This will let you select the mails that
you want to receive.
<p>
By default you will get:
<tag><tt>bts-control</tt>
<item>
-The control mails notifying a status change in one of the bugs.
+The email notifications from <email>control@bugs.debian.org</email>
+about bug report status changes.
<tag><tt>upload-source</tt>
<item>
-The
confirmation mail from <prgn>katie</prgn> when an uploaded source
+The
email notification from <prgn>katie</prgn> when an uploaded source
package is accepted.
<tag><tt>katie-other</tt>
<item>
-Other warning and error mails from <prgn>katie</prgn> (like the
-override disparity for the section or priority field).
+Other warning and error emails from <prgn>katie</prgn> (such as an
+override disparity for the section and/or the 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.
+Any non-automatic email sent to the PTS by people who wanted to
+contact the subscribers of the package. This can be done by sending mail
+to <tt><var>sourcepackage</var>@&pts-host;</tt>. In order to prevent spam,
+all messages sent to these addresses must contain the <tt>X-PTS-Approved</tt>
+header with a non-empty value.
<tag><tt>summary</tt>
<item>
-In the future, you may receive regular summary mails to keep you
-informed of the package's status (bug statistics, porting overview,
-progression in <em>testing</em>, ...).
+(This is a planned expansion.)
+The regular summary emails about the package's status (bug statistics,
+porting overview, progression in <em>testing</em>, ...).
</taglist>
+
<p>
-You can also decide to receive some more information:
+You can also decide to receive additional information:
<taglist>
<tag><tt>upload-binary</tt>
<item>
-The confirmation mail from <prgn>katie</prgn> when an uploaded binary
-package is accepted (to check that your package is recompiled for all
-architectures).
+The email notification from <prgn>katie</prgn> when an uploaded binary
+package is accepted. In other words, whenever a build daemon or a porter
+uploads your package for another architecture, you can get an email to
+track how your package gets recompiled for all architectures.
<tag><tt>cvs</tt>
<item>
-CVS commits if the maintainer has setup a system to forward commit
-notification to the PTS.
+CVS commit notifications, if the package has a CVS repository and the
+maintainer has set up forwarding commit notifications to the PTS.
<tag><tt>ddtp</tt>
<item>
<taglist>
-<tag><tt>subscribe <srcpackage> [<email>]</tt>
+<tag><tt>subscribe <sourcepackage> [<email>]</tt>
<item>
Subscribes <var>email</var> to communications related to the source package
- <var>srcpackage</var>. Sender address is used if the second argument is
- not present. If <var>srcpackage</var> is not a valid source package,
+ <var>sourcepackage</var>. Sender address is used if the second argument is
+ not present. If <var>sourcepackage</var> is not a valid source package,
you'll get a warning. However if it's a valid binary package, the PTS
will subscribe you to the corresponding source package.
-<tag><tt>unsubscribe <srcpackage> [<email>]</tt>
+<tag><tt>unsubscribe <sourcepackage> [<email>]</tt>
<item>
- Removes a previous subscription to the source package <var>srcpackage</var>
+ Removes a previous subscription to the source package <var>sourcepackage</var>
using the specified email address or the sender address if the second
argument is left out.
<tag><tt>keyword [<email>]</tt>
<item>
- Tells you the keywords that you are accepting. Each mail sent through
- the Package Tracking System is associated to a keyword and you receive
- only the mails associated to keywords that you are accepting. Here is
- the list of available keywords:
+ Tells you the keywords that you are accepting.
+ For an explanation of keywords, <qref id="pkg-tracking-system">see
+ above</qref>. Here's a quick summary:
<list>
<item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
- <item><tt>bts-control</tt>: reply to mails sent to
- <email>control@bugs.debian.org</email>
+ <item><tt>bts-control</tt>: reply to mails sent to &email-bts-control;
<item><tt>summary</tt>: automatic summary mails about the state of a package
<item><tt>cvs</tt>: notification of CVS commits
<item><tt>ddtp</tt>: translations of descriptions and debconf templates
<item><tt>default</tt>: all the other mails (those which aren't "automatic")
</list>
-<tag><tt>keyword <srcpackage> [<email>]</tt>
+<tag><tt>keyword <sourcepackage> [<email>]</tt>
<item>
- Same as previous item but for the given source package since
+ Same as the previous item but for the given source package, since
you may select a different set of keywords for each source package.
<tag><tt>keyword [<email>] {+|-|=} <list of keywords></tt>
Accept (+) or refuse (-) mails associated to the given keyword(s).
Define the list (=) of accepted keywords.
-<tag><tt>keyword <srcpackage> [<email>] {+|-|=} <list of keywords></tt>
+<tag><tt>keyword <sourcepackage> [<email>] {+|-|=} <list of keywords></tt>
<item>
Same as previous item but overrides the keywords list for the
indicated source package.
<sect1 id="pts-mail-filtering">Filtering PTS mails
<p>
Once you are subscribed to a package, you will get the mails sent to
-<tt><var>srcpackage</var>@packages.qa.debian.org</tt>. Those mails
+<tt><var>sourcepackage</var>@packages.qa.debian.org</tt>. Those mails
have special headers appended to let you filter them in a special
-mailbox with <prgn>procmail</prgn>. The added headers are
+mailbox (e.g. with <prgn>procmail</prgn>). The added headers are
<tt>X-Loop</tt>, <tt>X-PTS-Package</tt>, <tt>X-PTS-Keyword</tt> and
<tt>X-Unsubscribe</tt>.
<p>
<p>
If you use a publicly accessible CVS repository for maintaining
your Debian package you may want to forward the commit notification
-to the PTS so that the subscribers (possible co-maintainers) can
+to the PTS so that the subscribers (and possible co-maintainers) can
closely follow the package's evolution.
<p>
-It's very easy to setup. Once your CVS repository generates commit
-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.
+Once you set up the CVS repository to generate commit notifications,
+you just have to make sure it sends a copy of those mails
+to <tt><var>sourcepackage</var>_cvs@&pts-host;</tt>. Only the people
+who accept the <em>cvs</em> keyword will receive these notifications.
+
+ <sect1 id="pts-web">The PTS web interface
+ <p>
+The PTS has a web interface at <url id="http://&pts-host;/"> that puts
+together a lot of information about each source package. It features many useful
+links (BTS, QA stats, contact information, DDTP translation status,
+buildd logs) and gathers much 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 allows easy subscription to
+the PTS via email.
+ <p>
+You can jump directly to the web page concerning a specific source package
+with a URL like <tt>http://&pts-host;/<var>sourcepackage</var></tt>.
+ <p>
+This web interface has been designed like a portal for the development of
+packages: you can add custom content on your packages' pages. You can
+add "static information" (news items that are meant to stay available
+indefinitely) and news items in the "latest news" section.
+ <p>
+Static news items can be used to indicate:
+<list>
+<item>the availability of a project hosted on <qref id="alioth">Alioth</qref> for co-maintaining the package
+<item>a link to the upstream web site
+<item>a link to the upstream bug tracker
+<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 items may be used to announce that:
+<list>
+<item>beta packages are available for testing
+<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 they wish 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
+an email 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 having 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 a 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>
+Here are a few examples of valid mails used to generate news items in
+the PTS. The first one adds a link to the cvsweb interface of debian-cd
+in the "Static information" section:
+<example>
+From: Raphael Hertzog <hertzog@debian.org>
+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>
+ <p>
+The second one is an announcement 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 <hertzog@debian.org>
+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 item 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 item that will deprecate the
+information contained in the previous one.
<sect id="ddpo">Developer's packages overview
<p>
you don't forget any open bug, and so that you don't forget which
packages are under your responsibility.
+ <sect id="alioth">Debian *Forge: Alioth
+ <p>
+Alioth is a fairly new Debian service, based on a slightly modified version
+of the GForge software (which evolved from SourceForge). This software
+offers developers access to easy-to-use tools such as bug trackers, patch
+manager, project/task managers, file hosting services, mailing lists, CVS
+repositories etc. All these tools are managed via a web interface.
+ <p>
+It is intended to provide facilities to free software projects backed or led
+by Debian, facilitate contributions from external developers to projects
+started by Debian, and help projects whose goals are the promotion of Debian
+or its derivatives.
+ <p>
+For more information please visit <url id="&url-alioth;">.
+
<chapt id="pkgs">Managing Packages
<p>
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>
+ <sect1 id="upload-stable">
+ <heading>Special case: uploads to the <em>stable</em> distribution</heading>
<p>
Uploading to <em>stable</em> means that the package will be placed into the
<file>stable-proposed-updates</file> directory of the Debian archive for further
Extra care should be taken when uploading to <em>stable</em>. Basically, a
package should only be uploaded to stable if one of the following happens:
<list>
- <item>a security problem (e.g. a Debian security advisory)
<item>a truly critical functionality problem
<item>the package becomes uninstallable
<item>a released architecture lacks the package
</list>
+<p>
+In the past, uploads to <em>stable</em> were used to address security
+problems as well. However, this practice is deprecated, as uploads
+used for Debian security advisories are automatically copied to the
+appropriate <file>proposed-updates</file> archive when the advisory is
+released. See <ref id="bug-security"> for detailed information on
+handling security problems.
<p>
It is discouraged to change anything else in the package that isn't
-important, because even trivial fixes can cause bugs later on. Uploading
-new upstream versions to fix security problems is deprecated; applying the
-specific patch from the new upstream version to the old one ("back-porting"
-the patch) is the right thing to do in most cases.
+important, because even trivial fixes can cause bugs later on.
<p>
Packages uploaded to <em>stable</em> need to be compiled on systems running
<em>stable</em>, so that their dependencies are limited to the libraries
<em>stable</em>, because otherwise the package won't be considered for
inclusion.
- <sect1 id="upload-t-p-u">Uploads to <em>testing-proposed-updates</em>
+ <sect1 id="upload-t-p-u">
+ <heading>Special case: uploads to <em>testing-proposed-updates</em></heading>
<p>
The testing distribution is fed with packages from unstable according to the rules
explained in <ref id="testing">. However, the release manager may stop the testing
if you use anonymous FTP to upload, place them into
&upload-queue;.
<p>
+If you want to use feature described in <ref id="delayed-incoming">,
+you'll have to upload to <tt>ftp-master</tt>. It is the only upload
+point that supports delayed incoming.
+ <p>
Please note that you should transfer
the changes file last. Otherwise, your upload may be rejected because the
archive maintenance software will parse the changes file and see that not
<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>
-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">.
+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
+and 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>Monitoring bugs
+ <sect1 id="bug-monitoring">Monitoring bugs
<p>
If you want to be a good maintainer, you should periodically check the
<url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
<sect1 id="bug-answering">Responding to bugs
<p>
-Make sure that any discussion you have about bugs are sent both to
-the original submitter of the bug, and the bug itself (e.g.,
-<email>123@bugs.debian.org</email>). If you're writing a new
+When responding to bugs, make sure that any discussion you have about
+bugs is sent both to the original submitter of the bug, and to the bug
+itself (e.g., <email>123@&bugs-host;</email>). If you're writing a new
mail and you don't remember the submitter email address, you can
-use the <email>123-submitter@bugs.debian.org</email> email to
+use the <email>123-submitter@&bugs-host;</email> email to
contact the submitter <em>and</em> to record your mail within the
bug log (that means you don't need to send a copy of the mail to
-<email>123@bugs.debian.org</email>).
+<email>123@&bugs-host;</email>).
+ <p>
+If you get a bug which mentions "FTBFS", that means "Fails to build
+from source". Porters frequently use this acronym.
<p>
Once you've dealt with a bug report (e.g. fixed it), mark it as
<em>done</em> (close it) by sending an explanation message to
-<email>123-done@bugs.debian.org</email>. If you're fixing a bug by
+<email>123-done@&bugs-host;</email>. If you're fixing a bug by
changing and uploading the package, you can automate bug closing as
described in <ref id="upload-bugfix">.
<p>
are described in the <url id="&url-bts-devel;" name="BTS documentation for
Debian developers">. Operations such as reassigning, merging, and tagging
bug reports are described in the <url id="&url-bts-control;" name="BTS
-control bot documentation">. This section contains
+control server documentation">. This section contains
some guidelines for managing your own bugs, based on the collective
Debian developer experience.
<p>
<sect1 id="upload-bugfix">When bugs are closed by new uploads
<p>
-If you fix a bug in your packages, it is your responsibility as the
-package maintainer to close the bug when it has been fixed. However,
+As bugs and problems are fixed your packages, it is your
+responsibility as the package maintainer to close the bug. However,
you should not close the bug until the package which fixes the bug has
been accepted into the Debian archive. Therefore, once you get
notification that your updated package has been installed into the
archive, you can and should close the bug in the BTS.
<p>
However, it's possible to avoid having to manually close bugs after the
-upload -- just list the fixed bugs in your <file>debian/changelog</file>
+upload — just list the fixed bugs in your <file>debian/changelog</file>
file, following a certain syntax, and the archive maintenance software
will close the bugs for you. For example:
* Added man page. Closes: #98725.
</example>
-Technically speaking, the following Perl regular expression is what is
-used:
+Technically speaking, the following Perl regular expression describes
+how bug closing changelogs are identified:
<example>
/closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
</example>
-The author prefers the <tt>closes: #<var>XXX</var></tt> syntax, as
-one of the most concise and easiest to integrate with the text of the
+We prefer the <tt>closes: #<var>XXX</var></tt> syntax, as it is the
+most concise entry and the easiest to integrate with the text of the
<file>changelog</file>.
<p>
-If you happen to mistype a bug number or forget one in the changelog file,
-don't hesitate to undo any damage the error caused. To reopen wrongly closed
-bugs, send an <tt>reopen <var>XXX</var></tt> command in the bug tracking
-system's control bot. To close any remaining bugs that were fixed by your
-upload, email the <file>.changes</file> file to
-<email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your
-bug number.
- <p>
-Bear in mind that it is not obligatory to close bugs using the changelog
-like described above -- if you simply want to close bugs that don't have
-anything to do with an upload of yours, do it simply by emailing an
-explanation to <email>XXX-done@bugs.debian.org</email>.
-Do <strong>not</strong> close bugs in the changelog entry of a version
-if the said version of the package doesn't have anything to do with the bug.
+If you happen to mistype a bug number or forget a bug in the changelog
+entries, don't hesitate to undo any damage the error caused. To reopen
+wrongly closed bugs, send an <tt>reopen <var>XXX</var></tt> command to
+the bug tracking system's control address, &email-bts-control;. To
+close any remaining bugs that were fixed by your upload, email the
+<file>.changes</file> file to <email>XXX-done@&bugs-host;</email>,
+where <var>XXX</var> is your bug number.
+ <p>
+Bear in mind that it is not obligatory to close bugs using the
+changelog as described above. If you simply want to close bugs that
+don't have anything to do with an upload you made, do it by emailing
+an explanation to <email>XXX-done@&bugs-host;</email>. Do
+<strong>not</strong> close bugs in the changelog entry of a version if
+the changes in that version of the package doesn't have any bearing on
+the bug.
<p>
-For general information on what to put in the changelog files, please
-refer to <ref id="bpp-debian-changelog">.
+For general information on how to write your changelog entries, see
+<ref id="bpp-debian-changelog">.
+
<sect1 id="bug-security">Handling security-related bugs
<p>
<!-- information about the security database goes here once it's ready -->
<!-- (mdz) -->
- <sect2 id="bug-security-you">What to do when you learn of a
- security problem
- <p>
+<p>
When you become aware of a security-related bug in a Debian package,
whether or not you are the maintainer, collect pertinent information
-about the problem, and promptly contact the security team at
-&email-security-team;.
-Useful information includes, for example:
+about the problem, and promptly contact the security team at
+&email-security-team; as soon as possible. Useful information
+includes, for example:
<list compact>
<item>What versions of the package are known to be affected by the
especially helpful)
<item>Any fixed packages that you have prepared yourself (send only
- the <tt>.diff.gz</tt> and <tt>.dsc</tt> files)
+ the <tt>.diff.gz</tt> and <tt>.dsc</tt> files and read <ref
+ id="bug-security-building"> first)
+
+ <item>Any assistance you can provide to help with testing (exploits,
+ regression testing, etc.)
<item>Any information needed for the advisory (see <ref
id="bug-security-advisories">)
<sect2 id="bug-security-confidentiality">Confidentiality
<p>
Unlike most other activities within Debian, information about security
-issues must sometimes be kept private for a time. Whether this is the
+issues must sometimes be kept private for a time.
+This allows software distributors to coordinate their disclosure in
+order to minimize their users' exposure. Whether this is the
case depends on the nature of the problem and corresponding fix, and
whether it is already a matter of public knowledge.
+
<p>
There are a few ways a developer can learn of a security problem:
possible options for dealing with the problem:
<list>
- <item>if it is a trivial problem (like insecure temporary files)
- there is no need to keep the problem a secret and a fix should be
- made and released.
+ <item>If the security exposure is minor, there is sometimes no need
+ to keep the problem a secret and a fix should be made and released.
- <item>if the problem is severe (remotely exploitable, possibility to
- gain root privileges) it is preferable to share the information with
+ <item>If the problem is severe, it is preferable to share the
+ information with
other vendors and coordinate a release. The security team keeps
contacts with the various organizations and individuals and can take
care of that.
</list>
<p>
- In all cases if the person who reports the problem asks to not
- disclose the information that should be respected, with the obvious
- exception of informing the security team (make sure you tell the
- security team that the information can not be disclosed).
+ In all cases if the person who reports the problem asks that it not
+ be disclosed, such requests should be honored, with the obvious
+ exception of informing the security team in order that a fix may be
+ produced for a stable release of Debian. When sending confidential
+ information to the security team, be sure to mention this fact.
<p>
-Please note that if secrecy is needed you can also not upload a fix to
-unstable (or anywhere else), since the changelog and diff information
-for unstable is public.
+Please note that if secrecy is needed you may not upload a fix to
+unstable (or anywhere else, such as a public CVS repository). It is
+not sufficient to obfuscate the details of the change, as the code
+itself is public, and can (and will) be examined by the general public.
<p>
There are two reasons for releasing information even though secrecy is
<sect2 id="bug-security-advisories">Security Advisories
<p>
Security advisories are only issued for the current, released stable
-distribution, not for testing or unstable. When released, advisories
+distribution, and <em>not</em> for testing or unstable. When released,
+advisories
are sent to the &email-debian-security-announce;
+
mailing list and posted on <url
id="&url-debian-security-advisories;" name="the security web page">.
Security advisories are written and posted by the security
-team. However they certainly do not mind if a maintainer can supply
-some of the information for them, or write part of the
-text. Information that should be in an advisory includes:
+team. However they certainly do not mind if a
+maintainer can supply some of the information for them, or write part
+of the text. Information that should be in an advisory includes:
<list compact>
<item>A description of the problem and its scope, including:
<list>
<item>The type of problem (privilege escalation, denial of
service, etc.)
+ <item>What privileges may be gained, and by whom (if any)
<item>How it can be exploited
<item>Whether it is remotely or locally exploitable
<item>How the problem was fixed
</list>
+
+ This information allows users to assess the threat to their systems.
+
<item>Version numbers of affected packages
<item>Version numbers of fixed packages
<item>Information on where to obtain the updated packages
+ (usually from the Debian security archive)
<item>References to upstream advisories, <url
id="http://cve.mitre.org" name="CVE"> identifiers, and any other
information useful in cross-referencing the vulnerability
<heading>Preparing packages to address security issues</heading>
<p>
One way that you can assist the security team in their duties is to
-provide fixed packages suitable for a security advisory for the stable
+provide them with fixed packages suitable for a security advisory for
+the stable
Debian release.
<p>
When an update is made to the stable release, care must be taken to
avoid changing system behavior or introducing new bugs. In order to
do this, make as few changes as possible to fix the bug. Users and
administrators rely on the exact behavior of a release once it is
- made, so any change that is made might break someone's system.
- This is especially true of libraries: make sure you never change the
- API or ABI, no matter how small the change.
+ made, so any change that is made might break someone's system. This
+ is especially true of libraries: make sure you never change the API or
+ ABI, no matter how small the change.
<p>
This means that moving to a new upstream version is not a good
solution. Instead, the relevant changes should be back-ported to the
In some cases, it is not possible to back-port a security fix, for
example when large amounts of source code need to be modified or
rewritten. If this happens, it may be necessary to move to a new
-upstream version. However, you must always coordinate that with the
-security team beforehand.
+upstream version. However, this is only done in extreme situations,
+and you must always coordinate that with the security team beforehand.
<p>
Related to this is another important guideline: always test your
changes. If you have an exploit available, try it and see if it
stable release, this is <tt>oldstable-security</tt>. Do not target
<var>distribution</var>-proposed-updates!
+ <item>Make descriptive, meaningful changelog entries. Others will
+ rely on them to determine whether a particular bug was fixed.
+ Whenever possible, include an external reference, preferably a CVE
+ identifier, so that it can be cross-referenced.
+
<item>Make sure the version number is proper. It must be greater
than the current package, but less than package versions in later
distributions. If in doubt, test it with <tt>dpkg
normal archive, otherwise it is not possible to move the security
fix into the main archives later.
- <item>Be sure, when compiling a package, to compile on a clean
+ <item>Be sure to build the package on a clean
system which only has packages installed from the distribution you
are building for. If you do not have such a system yourself, you
can use a debian.org machine (see <ref id="server-machines">)
<sect2 id="bug-security-upload">Uploading the fixed package
<p>
-<em>DO NOT</em> upload a package to the security upload queue without
+Do <strong>NOT</strong> upload a package to the security upload queue
+(oldstable-security, stable-security, etc.) without
prior authorization from the security team. If the package does not
exactly meet the team's requirements, it will cause many problems and
delays in dealing with the unwanted upload.
<p>
-<em>DO NOT</em> upload your fix to proposed-updates without
+Do <strong>NOT</strong> upload your fix to proposed-updates without
coordinating with the security team. Packages from
security.debian.org will be copied into the proposed-updates directory
automatically. If a package with the same or a higher version number
<var>distribution</var>-proposed-updates on ftp-master or in the non-US
archive.
-
<sect id="archive-manip">
<heading>Moving, removing, renaming, adopting, and orphaning
packages</heading>
``binary-indep'' targets, as the Debian Policy Manual requires.
Make sure that both targets work independently, that is, that you can
call the target without having called the other before. To test this,
-try to run <tt>dpkg-buildpackage -b</tt>.
+try to run <tt>dpkg-buildpackage -B</tt>.
</enumlist>
Co-maintainers are all the other maintainers.</p>
<p>
In its most basic form, the process of adding a new co-maintainer is
-quite easy:<list>
+quite easy:
+<list>
<item>
<p>
Setup the co-maintainer with access to the sources you build the
should subscribe themselves to the appropriate source package.</p>
</item>
</list></p>
+ <p>
+Collaborative maintenance can often be further eased with the use of
+tools on Alioth (see <ref id="alioth">).
</sect>
-
<chapt id="best-pkging-practices">
<heading>Best Packaging Practices</heading>
<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
</sect1>
</sect>
- <sect id="bpp-debian-maint-scripts">
+
+ <sect id="bpp-debian-control">
+ <heading>Best practices for <file>debian/control</file></heading>
+ <p>
+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>
+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 — "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>
+
+
+ <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:
+
+<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 sentence 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 sentence.
+ </sect1>
+
+ <sect1 id="bpp-pkg-desc">
+ <heading>The long description</heading>
+ <p>
+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 long description should consist of full and complete sentences.
+ <p>
+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 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>
+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>
+ </sect1>
+
+
+ <sect1 id="bpp-upstream-info">
+ <heading>Upstream home page</heading>
+ <p>
+We recommend that you add the URL for the package's home page to the
+package description in <file>debian/control</file>. This information
+should be added at the
+end of description, using the following format:
+
+<example> .
+ Homepage: http://some-project.some-place.org/</example>
+
+Note the spaces prepending the line, which serves to break the lines
+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 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
+<tt>&packages-host;</tt>. If you don't want to bother migrating the
+home page from the description to this field, you should probably wait
+until that is available.</p>
+ </sect1>
+ </sect>
+
+
+ <sect id="bpp-debian-changelog">
+ <heading>Best practices for <file>debian/changelog</file></heading>
+ <p>
+The following practices supplement the <url name="Policy on changelog
+files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
+
+ <sect1 id="bpp-changelog-do">
+ <heading>Writing useful changelog entries</heading>
+ <p>
+The changelog entry for a package revision documents changes in that
+revision, and only them. Concentrate on describing significant and
+user-visible changes that were made since the last version.
+ <p>
+Focus on <em>what</em> was changed — who, how and when are
+usually less important. Having said that, remember to politely
+attribute people who have provided notable help in making the package
+(e.g., those who have sent in patches).
+ <p>
+There's no need to elaborate the trivial and obvious changes. You can
+also aggregate several changes in one entry. On the other hand, don't
+be overly terse if you have undertaken a major change. Be especially
+clear if there are changes that affect the behaviour of the program.
+For further explanations, use the <file>README.Debian</file> file.
+ <p>
+Use common English so that the majority of readers can comprehend it.
+Avoid abbreviations, "tech-speak" and jargon when explaining changes
+that close bugs, especially for bugs filed by users that did not
+strike you as particularly technically savvy. Be polite, don't swear.
+ <p>
+It is sometimes desirable to prefix changelog entries with the names
+of the files that were changed. However, there's no need to
+explicitly list each and every last one of the changed files,
+especially if the change was small or repetitive. You may use
+wildcards.
+ <p>
+When referring to bugs, don't assume anything. Say what the problem
+was, how it was fixed, and append the "closes: #nnnnn" string. See
+<ref id="upload-bugfix"> for more information.
+
+
+ <sect1 id="bpp-changelog-misconceptions">
+ <heading>Common misconceptions about changelog entries</heading>
+ <p>
+The changelog entries should <strong>not</strong> document generic
+packaging issues ("Hey, if you're looking for foo.conf, it's in
+/etc/blah/."), since administrators and users are supposed to be at
+least remotely acquainted with how such things are generally arranged
+on Debian systems. Do, however, mention if you change the location of
+a configuration file.
+ <p>
+The only bugs closed with a changelog entry should be those that are
+actually fixed in the same package revision. Closing unrelated bugs
+in the changelog is bad practice. See <ref id="upload-bugfix">.
+ <p>
+The changelog entries should <strong>not</strong> be used for random
+discussion with bug reporters ("I don't see segfaults when starting
+foo with option bar; send in more info"), general statements on life,
+the universe and everything ("sorry this upload took me so long, but I
+caught the flu"), or pleas for help ("the bug list on this package is
+huge, please lend me a hand"). Such things usually won't be noticed
+by their target audience, but may annoy people who wish to read
+information about actual changes in the package. See <ref
+id="bug-answering"> for more information on how to use the bug
+tracking system.
+ <p>
+It is an old tradition to acknowledge bugs fixed in non-maintainer
+uploads in the first changelog entry of the proper maintainer upload,
+for instance, in a changelog entry like this:
+<example>
+ * Maintainer upload, closes: #42345, #44484, #42444.
+</example>
+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">
+ <heading>Common errors in changelog entries</heading>
+ <p>
+The following examples demonstrate some common errors or example of
+bad style in changelog entries.
+
+ <p>
+<example>
+ * Fixed all outstanding bugs.
+</example>
+This doesn't tell readers anything too useful, obviously.
+
+ <p>
+<example>
+ * Applied patch from Jane Random.
+</example>
+What was the patch about?
+
+ <p>
+<example>
+ * Late night install target overhaul.
+</example>
+Overhaul which accomplished what? Is the mention of late night
+supposed to remind us that we shouldn't trust that code?
+
+ <p>
+<example>
+ * Fix vsync FU w/ ancient CRTs.
+</example>
+Too many acronyms, and it's not overly clear what the, uh, fsckup (oops,
+a curse word!) was actually about, or how it was fixed.
+
+ <p>
+<example>
+ * This is not a bug, closes: #nnnnnn.
+</example>
+First of all, there's absolutely no need to upload the package to
+convey this information; instead, use the bug tracking system.
+Secondly, there's no explanation as to why the report is not a bug.
+
+ <p>
+<example>
+ * Has been fixed for ages, but I forgot to close; closes: #54321.
+</example>
+If for some reason you didn't mention the bug number in a previous changelog
+entry, there's no problem, just close the bug normally in the BTS. There's
+no need to touch the changelog file, presuming the description of the fix is
+already in (this applies to the fixes by the upstream authors/maintainers as
+well, you don't have to track bugs that they fixed ages ago in your
+changelog).
+
+ <p>
+<example>
+ * Closes: #12345, #12346, #15432
+</example>
+Where's the description? If you can't think of a descriptive message,
+start by inserting the title of each different bug.
+ </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">
+-->
+
+
+ <sect id="bpp-debian-maint-scripts">
<heading>Best practices for maintainer scripts</heading>
<p>
Maintainer scripts include the files <file>debian/postinst</file>,
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 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>
-
- <sect1 id="bpp-pkg-desc">
- <heading>Writing useful descriptions</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.
- <p>
-The following practices supplement the <url name="Policy on the descriptions
-of packages" id="&url-debian-policy;ch-miscellaneous.html#s-descriptions">.
- <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.
- <p>
-The long description should, however, always consist of full sentences.
- <p>
-Since the first user impression is based on the description, 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>
-We recommend that you add the URL for the package's home page to the
-package description in <file>debian/control</file>. This information
-should be added at the
-end of description, using the following format:
-
-<example> .
- Homepage: http://some-project.some-place.org/</example>
-
-Note the spaces prepending the line, which serves to break the lines
-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.
- <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
-<tt>&packages-host;</tt>. If you don't want to bother migrating the
-home page from the description to this field, you should probably wait
-until that is available.</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).
--->
-
<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
future.
<p>
Debconf is a great tool but it is often poorly used. Many common mistakes
-are listed in the <manref name="debconf-devel" section="8"> man page.
+are listed in the <manref name="debconf-devel" section="7"> man page.
It is something that you must read if you decide to use debconf.
</sect>
sympa may be an example package
-->
- <sect1 id="bpp-archindepdata">Architecture-independent data
- <p>
- It is not uncommon to have a large amount of architecture-independent
- data packaged with a program. For example, collection of icons,
- wallpapers or other graphic files, or audio files. If the size of
- this data is negligible compared to the size of the remainder of the
- package, you can keep it all in the same 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 adds some extra overhead into the Packages files, it can save a
- lot of disk space on Debian mirrors, and it also reduces processing
- time of Lintian or Linda when run over the entire Debian archive.
- </sect1>
-
+ <sect1 id="bpp-archindepdata">
+ <heading>Architecture-independent data</heading>
+ <p>
+It is not uncommon to have a large amount of architecture-independent
+data packaged with a program. For example, audio files, a collection
+of icons, wallpaper patterns, or other graphic files. If the size of
+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, 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
+<prgn>lintian</prgn> or <prgn>linda</prgn> (see <ref id="tools-lint">)
+when run over the entire Debian archive.
+ </sect1>
</sect>
- <sect id="bpp-debian-changelog">
- <heading>Best practices for <file>debian/changelog</file></heading>
- <p>
-The following practices supplement the <url name="Policy on changelog
-files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
-
- <sect1 id="bpp-changelog-do">
- <heading>Writing useful changelog entries</heading>
- <p>
-The changelog entry for a package revision documents changes in that
-revision, and only them. Concentrate on describing changes you did since
-the last version that are worth mentioning.
- <p>
-Focus on <em>what</em> was changed; who, how and when are usually less
-important. Having said that, remember to politely attribute people who have
-provided notable help in making the package (e.g. those who have sent in
-patches).
- <p>
-There's no need to elaborate the trivial and obvious changes. You can also
-aggregate several such changes in one entry. However, don't be overly terse
-if you have undertaken a major change. Be especially clear if there are
-changes that affect the behaviour of the program -- and for further
-explanations, use the <file>README.Debian</file> file.
- <p>
-Use common English language, one which the majority of viewers can
-understand. Avoid abbreviations, "tech-speak" and jargon when explaining
-changes that close bugs, especially if the said bugs were filed by users
-that did not strike you as particularly techically savvy. Also, be polite,
-don't swear.
- <p>
-It is customary to prefix changelog entries with the names of the files that
-were changed. There's no need to explicitely list each and every last one of
-the changed files, especially if the change was small or repetitive -- use
-wildcard characters wisely.
- <p>
-When referring to bugs, don't assume anything -- say what the problem was,
-how it was fixed, and append the "closes: #nnnnn" string.
-See <ref id="upload-bugfix"> for more information.
-
- <sect1 id="bpp-changelog-dont">
- <heading>Common misconceptions about changelog entries</heading>
- <p>
-The changelog entries should <strong>not</strong> document generic packaging
-issues ("Hey, if you're looking for foo.conf, it's in /etc/blah/."), since
-administrators and users are supposed to be at least remotely acquainted
-with how such things are generally arranged on Debian systems. Do, however,
-mention if you change the location of a configuration file.
- <p>
-The only bugs closed with a changelog entry should be those that are
-actually fixed in the same package revision. Closing bugs unrelated bugs in
-the changelog is considered very bad practice. See <ref id="upload-bugfix">.
- <p>
-The changelog entries should <strong>not</strong> be used for random
-discussion with bug reporters ("I don't see segfaults when starting foo
-with option bar; send in more info.") or pleas for help ("The bug list
-on this package is huge, please lend me a hand."). Such things usually
-won't be noticed by their target audience, but will on the other hand
-annoy people who wish to read information about actual changes in the
-package. Please see <ref id="bug-answering"> for more information on
-how to use the bug tracking system.
- <p>
-It is an old tradition to acknowledge bugs fixed in non-maintainer uploads
-in the first changelog entry of the real maintainer. You don't have to
-follow it, though: if you are certain that you will include the changes from
-the NMU in your next release, you can simply close the bugs the normal way.
-It's usually polite to note that the bugs were fixed by another developer.
- <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.
-
- <sect2 id="bpp-changelog-dont-really-dont">
- <heading>Common errors in changelog entries</heading>
- <p>
-<example>
- * Fixed all outstanding bugs.
-</example>
- <p>
-This doesn't tell readers anything too useful, obviously. Don't do that(TM).
-
-<example>
- * Applied patch from Jane Random.
-</example>
- <p>
-What was the patch about?
-
-<example>
- * Late night install target overhaul.
-</example>
- <p>
-Overhaul which accomplished...? Is the mention of late night supposed to
-remind us that we shouldn't trust that code?
-
-<example>
- * Fix vsync FU w/ ancient CRTs.
-</example>
- <p>
-Too many acronyms, and it's not overly clear what the fuckup (oops,
-a curse word!) was actually about, or how it was fixed.
-
-<example>
- * This is not a bug. Closes: #nnnnnn
-</example>
- <p>
-First of all, there's absolutely no need to upload the package to convey
-this information. Use the bug tracking system! Secondly, there's no
-explanation as to why the report is not a bug.
-
-<example>
- * Has been fixed for ages, but I forgot to close. Closes: #54321
-</example>
- <p>
-If for some reason you didn't mention the bug number in a previous changelog
-entry, there's no problem, just close the bug normally in the BTS. There's
-no need to touch the changelog file, presuming the description of the fix is
-already in (this applies to the fixes by the upstream authors/maintainers as
-well, you don't have to track bugs that they fixed ages ago in your
-changelog).
-
-<example>
- * Closes: #12345, #12346, #15432
-</example>
- <p>
-Where's the description?! If you can't think of a descriptive message, start
-by inserting the title of each different bug.
-
+ </chapt>
<chapt id="beyond-pkging">
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>
filing the same bug report simultaneously.
<p>
Note that when sending lots of bugs on the same subject, you should
-send the bug report to <email>maintonly@bugs.debian.org</email> so
+send the bug report to <email>maintonly@&bugs-host;</email> so
that the bug report is not forwarded to the bug distribution mailing
list.
email before the package is in acceptable shape. Being a sponsor
means being a mentor.
<p>
-Once the package meets Debian standards, build the package with
-<example>dpkg-buildpackage -us -uc</example> and sign it
-with <example>debsign -m"<var>FULLNAME</var> <var>email-addr</var>" <var>changes-file</var></example>
+Once the package meets Debian standards, build and sign it with
+<example>dpkg-buildpackage -k<var>KEY-ID</var></example>
before uploading it to the incoming directory.
<p>
The Maintainer field of the <file>control</file> file and the
<sect1 id="debdiff">
<heading><package>debdiff</package></heading>
<p>
-<prgn>debdiff</prgn> (from the <package>devscripts</package> package)
+<prgn>debdiff</prgn> (from the <package>devscripts</package> package, <ref id="devscripts">)
compares file lists and control files of two packages. It is a simple
regression test, as it will help you notice if the number of binary
packages has changed since the last upload, or if something's changed
<sect1 id="dpkg-depcheck">
<heading><package>dpkg-depcheck</package></heading>
<p>
-<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package> package)
+<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package>
+package, <ref id="devscripts">)
runs a command under <prgn>strace</prgn> to determine all the packages that
were used by the said command.
<p>
<!-- FIXME: add the following
questionable:
+ dbs (referred to above)
+ dpatch (referred to above)
+ debarchiver
ucf
dpkg-awk
grep-dctrl
~ianmdlvl / developers-reference.git / blobdiff