<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.129 $">
+ <!entity cvs-rev "$Revision: 1.150 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<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>
<version>ver. &version;, &date-en;
<copyright>
<copyrightsummary>
-copyright ©1998—2002 Adam Di Carlo</copyrightsummary>
+copyright © 1998—2002 Adam Di Carlo</copyrightsummary>
<copyrightsummary>
-copyright ©1997, 1998 Christian Schwarz</copyrightsummary>
+copyright © 2002 Raphaël Hertzog</copyrightsummary>
+ <copyrightsummary>
+copyright © 1997, 1998 Christian Schwarz</copyrightsummary>
<p>
This manual is free software; you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
to work on something to avoid duplicated effort.
<p>
Another good list to subscribe to is &email-debian-mentors;. See <ref
-id="mentors"> for details. The IRC channel <tt>#debian</tt> on the
-Linux People IRC network (e.g., <tt>irc.debian.org</tt>) can also be
+id="mentors"> for details. The IRC channel <tt>#debian</tt> can also be
helpful.
<p>
<sect id="rc-bugs">Managing release-critical bugs
<p>
-Release-critical bugs (RCB) are all bugs that have severity
-<em>critical</em>, <em>grave</em> or <em>serious</em>.
+Generally you should deal with bug reports on your packages as described in
+<ref id="bug-handling">. However, there's a special category of bugs that
+you need to take care of -- the so-called release-critical bugs (RC bugs).
+All bug reports that have severity <em>critical</em>, <em>grave</em> or
+<em>serious</em> are considered to have an impact on whether the package can
+be released in the next stable release of Debian.
Those bugs can delay the Debian release
and/or can justify the removal of a package at freeze time. That's why
-these bugs need to be corrected as quickly as possible. You must be
-aware that some developers who are part of the <url
-id="&url-debian-qa;" name="Debian Quality Assurance"> effort are
-following those bugs and try to help you whenever they are able. But if
-you can't fix such bugs within 2 weeks, you should either ask for help
+these bugs need to be corrected as quickly as possible.
+ <p>
+Developers who are part of the <url id="&url-debian-qa;"
+name="Quality Assurance"> group are following all such bugs, and trying
+to help whenever possible. If, for any reason, you aren't able fix an
+RC bug in a package of yours within 2 weeks, you should either ask for help
by sending a mail to the Quality Assurance (QA) group
&email-debian-qa;, or explain your difficulties and present a plan to fix
-them by sending a mail to the proper bug report. Otherwise, people
+them by sending a mail to the bug report. Otherwise, people
from the QA group may want to do a Non-Maintainer Upload (see
<ref id="nmu">) after trying to contact you (they might not wait as long as
usual before they do their NMU if they have seen no recent activity from you
<item>
Orphan all your packages, as described in <ref id="orphaning">.
<item>
-Send an email about how you are leaving the project to
+Send an email about why you are leaving the project to
&email-debian-private;.
<item>
Notify the Debian key ring maintainers that you are leaving by
<sect id="irc-channels">IRC channels
<p>
-Several IRC channels are dedicated to Debian's development. They are all
-hosted on the <url id="&url-openprojects;" name="OpenProjects"> network.
-The <tt>irc.debian.org</tt> DNS entry is just an alias to
+Several IRC channels are dedicated to Debian's development. They are mainly
+hosted on the <url id="&url-openprojects;" name="freenode"> network
+(previously known as Open Projects Network).
+The <tt>irc.debian.org</tt> DNS entry is an alias to
<tt>irc.openprojects.net</tt>.
<p>
-The main channel <em>#debian-devel</em> is very active since more
-than 150 persons are always logged in. It's a channel for people who work
+The main channel for Debian in general is <em>#debian</em>. This is a large,
+general-purpose channel where users can find recent news in the topic and
+served by bots. <em>#debian</em> is for English speakers; there are also
+<em>#debian.de</em>, <em>#debian-fr</em>, <em>#debian-br</em> and other
+similarly named channels for speakers of other languages.
+ <p>
+The main channel for Debian development is <em>#debian-devel</em>.
+It is a very active channel since usually over 150 people are always
+logged in. It's a channel for people who work
on Debian, it's not a support channel (there's <em>#debian</em> for that).
It is however open to anyone who wants to lurk (and learn). Its topic is
-always full of interesting information. Since it's an open channel, you
+commonly full of interesting information for developers.
+ <p>
+Since <em>#debian-devel</em> it's an open channel, you
should not speak there of issues that are discussed in
-&email-debian-private;. There's a key protected channel
-<em>#debian-private</em> for that purpose. The key is available
-in the archives of debian-private in
+&email-debian-private;. There's another channel for this purpose,
+it's called <em>#debian-private</em> and it's protected by a key.
+This key is available in the archives of debian-private in
<file>master.debian.org:&file-debian-private-archive;</file>,
just <prgn>zgrep</prgn> for <em>#debian-private</em> in
all the files.
<em>#debian-bugs</em> is used for coordinating bug squash parties.
<em>#debian-boot</em> is used to coordinate the work on the boot
floppies (i.e. the installer). <em>#debian-doc</em> is
-occasionally used to work on documentation like the one you are
+occasionally used to talk about documentation, like the document you are
reading. Other channels are dedicated to an architecture or a set of
-packages: <em>#debian-bsd</em>, <em>#debian-kde</em>,
+packages: <em>#debian-bsd</em>, <em>#debian-kde</em>, <em>#debian-jr</em>,
+<em>#debian-edu</em>,
<em>#debian-sf</em> (SourceForge package), <em>#debian-oo</em> (OpenOffice
package) ...
<p>
-Some non-English channels exist, for example <em>#debian-devel-fr</em> for
+Some non-English developers' channels exist as well, for example
+<em>#debian-devel-fr</em> for
French speaking people interested in Debian's development.
Generally speaking, you can use these machines for Debian-related purposes
as you see fit. Please be kind to system administrators, and do not use
up tons and tons of disk space, network bandwidth, or CPU without first
-getting the approval of the admins. Usually these machines are run by
+getting the approval of the system administrators. Usually these machines are run by
volunteers.
<p>
Please take care to protect your Debian passwords and SSH keys installed on
This database lets you register some other information like public SSH
keys that will be automatically installed on the official debian machines
or like *.debian.net DNS entry. Those features are documented
-here : <url id="&url-debian-db-mail-gw;">
+at <url id="&url-debian-db-mail-gw;">.
<sect id="servers-mirrors">Mirrors of Debian servers
<p>
and <tt>&non-us-host;</tt>.
<p>
Packages are uploaded by all the maintainers into a directory called
-<file>unchecked</file>. This directory is scanned every 15 minutes by the katie script
-that verifies the integrity of the uploaded packages and the cryptographic
+<file>unchecked</file>. This directory is scanned every 15 minutes by
+the <prgn>katie</prgn> script, which verifies the integrity of the uploaded packages and the cryptographic
signatures. If the package is considered ready to be installed, it
is moved into the <file>accepted</file> directory. If this is the first upload of
the package, it is moved in the <file>new</file> directory, where it waits
for an approval of the ftpmasters. If the package contains files to be installed
-"by-hand" is is moved in the <file>byhand</file> directory, where it waits
+"by-hand" it is moved in the <file>byhand</file> directory, where it waits
for a manual installation by the ftpmasters. Otherwise, if any error has been detected,
the package is refused and is moved in the <file>reject</file> directory.
<p>
The scripts are generating some output files to explain why some packages
are kept out of testing. They are available at <url
id="&url-testing-maint;">. Alternatively, it is possible to use
-the <prgn>grep-excuses</prgn> program part of the
-<package>devscripts</package> package. It can be easily put in a crontab
+the <prgn>grep-excuses</prgn> program which is in the
+<package>devscripts</package> package. It can be easily put in a
+<manref name="crontab" section="5">
to keep someone informed of the progression of his packages in <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-faq;" name="testing FAQ"> gives some more information
+id="&url-testing-maint;" name="testing overview"> 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
by the scripts. In that case, the release manager must be
contacted, and he will force the inclusion of the packages.
- <sect id="pkg-info">Package's information
+ <sect id="pkg-info">Package information
<p>
<sect1 id="pkg-info-web">On the web
<p>
-Each package has several dedicated web pages that contain a lot of
-information. <tt>http://&packages-host;/<var>package-name</var></tt>
-will display each version of the package
-available in the various distributions. The per-version detailed
-information includes the package description,
-the dependencies and links to download the package.
+Each package has several dedicated web pages.
+<tt>http://&packages-host;/<var>package-name</var></tt>
+displays each version of the package
+available in the various distributions. Each version links to a page
+which provides information, including the package description,
+the dependencies and package download links.
<p>
-The bug tracking system sorts the bugs by package, you can
-watch the bugs of each package at
+The bug tracking system track bugs for each package. You can
+view the bugs of a given package at the URL
<tt>http://&bugs-host;/<var>package-name</var></tt>.
<sect1 id="madison">The <prgn>madison</prgn> utility
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 than the maintainer. Each mail
+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
you want to receive.
<sect id="ddpo">Developer's packages overview
<p>
-This is a nice web portal that displays a table of all the packages
-of a single developer (including those where he's listed as
-co-maintainer). The table gives a good summary about his
-packages : number of bugs by severity, list of available versions in each
-distributon, testing status and much more including links to any other
+A QA (quality assurance) web portal is available at <url
+ id="&url-ddpo;"> which displays a table listing all the packages
+of a single developer (including those where the party is listed as
+a co-maintainer). The table gives a good summary about the developer's
+packages: number of bugs by severity, list of available versions in each
+distribution, testing status and much more including links to any other
useful information.
<p>
-It is a very good idea to take a look at this table regularly so that
-you don't forget any open bug and so that you don't forget which
+It is a good idea to look up your own data regularly so that
+you don't forget any open bug, and so that you don't forget which
packages are under your responsibility.
- <p>
-You will find everything here : <url id="&url-ddpo;">
<chapt id="pkgs">Managing Packages
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
scripts when he wants to freeze the distribution. In that case, you may want to
-upload to <em>testing-proposed-udaptes</em> to provide fixed packages during the freeze.
+upload to <em>testing-proposed-updates</em> to provide fixed packages during the freeze.
<p>
Keep in mind that packages uploaded there are not automatically processed, they
have to go through the hands of the release manager. So you'd better have a good
This usually involves shortening the period during which one is to wait
before uploading the fixes, and shortening the DELAYED period. It is
important to notice that even in these so-called "bug squashing party"
-times, the NMUer has to file bugs and contact the developer first,
+times, the NMU'er has to file bugs and contact the developer first,
and act later.
<sect1 id="nmu-guidelines">How to do a source NMU
<sect1 id="ack-nmu">Acknowledging an NMU
<p>
-If one of your packages has been NMUed, you have to incorporate the
+If one of your packages has been NMU'ed, you have to incorporate the
changes in your copy of the sources. This is easy, you just have
to apply the patch that has been sent to you. Once this is done, you
have to close the bugs that have been tagged fixed by the NMU. You
(see <ref id="collaborative-maint">).
- <sect id="porting">Porting and Being Ported
+ <sect id="porting">Porting and being ported
<p>
Debian supports an ever-increasing number of architectures. Even if
you are not a porter, and you don't use any architecture but one, it
blessing or status, so buyer, beware.
- <sect1>Tools for porters
- <p>
-There are several tools available for the porting effort. This section
-contains a brief introduction to these tools; see the package
-documentation or references for full information.
-
-
- <sect2 id="quinn-diff">
- <heading><package>quinn-diff</package>
- <p>
-<package>quinn-diff</package> is used to locate the differences from
-one architecture to another. For instance, it could tell you which
-packages need to be ported for architecture <var>Y</var>, based on
-architecture <var>X</var>.
-
-
- <sect2 id="buildd">
- <heading><package>buildd</package>
- <p>
+ <sect1 id="porter-automation">
+ <heading>Porting infrastructure and automation</heading>
+ <p>
+There is infrastructure and several tools to help automate the package
+porting. This section contains a brief overview of this automation and
+portingto these tools; see the package documentation or references for
+full information.</p>
+
+ <sect2>
+ <heading>Mailing lists and web pages</heading>
+ <p>
+Web pages containing the status of each port can be found at <url
+id="&url-debian-ports;">.
+ <p>
+Each port of Debian has a mailing list. The list of porting mailing
+lists can be found at <url id="&url-debian-port-lists;">. These lists
+are used to coordinate porters, and to connect the users of a given
+port with the porters.</p>
+ </sect2>
+
+ <sect2>
+ <heading>Porter tools</heading>
+ <p>
+Descriptions of several porting tools can be found in <ref
+id="tools-porting">.</p>
+ </sect2>
+
+ <sect2 id="buildd">
+ <heading><package>buildd</package></heading>
+ <p>
The <package>buildd</package> system is used as a distributed,
client-server build distribution system. It is usually used in
conjunction with <em>auto-builders</em>, which are ``slave'' hosts
<p>
<package>buildd</package> is not yet available as a package; however,
most porting efforts are either using it currently or planning to use
-it in the near future. It collects a number of as yet unpackaged
+it in the near future. The actual automated builder is packaged as
+<package>sbuild</package>, see its description in <ref id="sbuild">.
+The complete <package>buildd</package> system also collects a number of as yet unpackaged
components which are currently very useful and in use continually,
-such as <prgn>andrea</prgn>, <prgn>sbuild</prgn> and
+such as <prgn>andrea</prgn> and
<prgn>wanna-build</prgn>.
<p>
Some of the data produced by <package>buildd</package> which is
from <prgn>andrea</prgn> (source dependencies) and
<package>quinn-diff</package> (packages needing recompilation).
<p>
-We are very excited about this system, since it potentially has so
-many uses. Independent development groups can use the system for
+We are quite proud of this system, since it has so
+many possible uses. Independent development groups can use the system for
different sub-flavors of Debian, which may or may not really be of
-general interest (for instance, a flavor of Debian built with gcc
+general interest (for instance, a flavor of Debian built with <prgn>gcc</prgn>
bounds checking). It will also enable Debian to recompile entire
distributions quickly.
+ </sect2>
- <sect2 id="dpkg-cross">
- <heading><package>dpkg-cross</package>
- <p>
-<package>dpkg-cross</package> is a tool for installing libraries and
-headers for cross-compiling in a way similar to
-<package>dpkg</package>. Furthermore, the functionality of
-<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
-enhanced to support cross-compiling.
-
<sect id="collaborative-maint">
<heading>Collaborative maintenance</heading>
<p>
"Collaborative maintenance" is a term describing the sharing of Debian
package maintenance duties by several people. This collaboration is
-almost a good idea, since it generally results in higher quality and
+almost always a good idea, since it generally results in higher quality and
faster bug fix turnaround time. It is strongly recommended that
packages in which a priority of <tt>Standard</tt> or which are part of
the base set have co-maintainers.</p>
</sect>
<sect id="archive-manip">
- <heading>Moving, Removing, Renaming, Adopting, and Orphaning
- Packages</heading>
+ <heading>Moving, removing, renaming, adopting, and orphaning
+ packages</heading>
<p>
Some archive manipulation operations are not automated in the Debian
upload process. These procedures should be manually followed by
your <file>debian/control</file> file to replace and conflict with the
obsolete name of the package (see the <url id="&url-debian-policy;"
name="Debian Policy Manual"> for details). Once you've uploaded
-that package, and the package has moved into the archive, file a bug
+the package and the package has moved into the archive, file a bug
against <tt>ftp.debian.org</tt> asking to remove the package with the
obsolete name. Do not forget to properly reassign the package's bugs
at the same time.
<p>
-At other times, you may make a mistake in constructing your package, and
+At other times, you may make a mistake in constructing your package and
wish to replace it. The only way to do this is to increase the version
-number, and upload a new version. The old version will be expired in
+number and upload a new version. The old version will be expired in
the usual manner. Note that this applies to each part of your package,
including the sources: if you wish to replace the upstream source tarball
of your package, you will need to upload it with a different version. An
bug log (that means you don't need to send a copy of the mail to
<email>123@bugs.debian.org</email>).
<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
+changing and uploading the package, you can automate bug closing as
+described in <ref id="upload-bugfix">.
+ <p>
You should <em>never</em> close bugs via the bug server <tt>close</tt>
command sent to &email-bts-control;. If you do so, the original
submitter will not receive any information about why the bug was
<p>
As a package maintainer, you will often find bugs in other packages or
have bugs reported against your packages which are actually bugs in
-other packages. The <url id="&url-bts-control;" name="BTS
-instructions"> document the technical operations of the BTS, such as
-how to file, reassign, merge, and tag bugs. This section contains
+other packages. The bug tracking system's features interesting to developers
+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
some guidelines for managing your own bugs, based on the collective
Debian developer experience.
<p>
Filing bugs for problems that you find in other packages is one of
the "civic obligations" of maintainership, see <ref id="submit-bug">
-for details. However handling the bugs on your own packages is
+for details. However, handling the bugs in your own packages is
even more important.
<p>
Here's a list of steps that you may follow to handle a bug report:
<list compact>
<item>What versions of the package are known to be affected by the
- bug.
-
- <item>The nature of the exposure (root compromise, user compromise,
- remote/local attack)
+ bug. Check each version that is present in a supported Debian
+ release, as well as testing and unstable.
<item>The nature of the fix, if any is available (patches are
especially helpful)
+
+ <item>Any fixed packages that you have prepared yourself (send only
+ the <tt>.diff.gz</tt> and <tt>.dsc</tt> files)
+
+ <item>Any information needed for the advisory (see <ref
+ id="bug-security-advisories">)
+
</list>
<sect2 id="bug-security-confidentiality">Confidentiality
There are a few ways a developer can learn of a security problem:
<list compact>
- <item>he notices it on a public forum (mailing list, website, etc.)
+ <item>he notices it on a public forum (mailing list, web site, etc.)
<item>someone files a bug report
<item>someone informs him via private email
</list>
<p>
There are two reasons for releasing information even though secrecy is
-requested: the problem has been known for too long, or the information
-has become public.
+requested: the problem has been known for a while, or that the problem
+or exploit has become public.
<sect2 id="bug-security-advisories">Security Advisories
<p>
<item>Version numbers of affected packages
<item>Version numbers of fixed packages
<item>Information on where to obtain the updated packages
+ <item>References to upstream advisories, <url
+ id="http://cve.mitre.org" name="CVE"> identifiers, and any other
+ information useful in cross-referencing the vulnerability
</list>
- <sect2 id="bug-security-building">Preparing packages to
- address security issues
+ <sect2 id="bug-security-building">
+ <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
Debian release.
<p>
When an update is made to the stable release, care must be taken to
- avoid changing system behaviour or introducing new bugs. In order 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 behaviour of a release once it is
- made, so any change we make can possibly break someone's system.
+ 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.
<p>
This means that moving to a new upstream version is not a good
-solution. Instead, the relevant changes should be backported to the
+solution. Instead, the relevant changes should be back-ported to the
version present in the current stable Debian release. Generally,
upstream maintainers are willing to help if needed. If not, the
Debian security team may be able to help.
<p>
-In some cases, it is not possible to backport a security fix, for
-example when large amounts of sourcecode need to be modified or
+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.
indeed succeeds on the unpatched package and fails on the fixed
package. Test other, normal actions as well, as sometimes a security
fix can break seemingly unrelated features in subtle ways.
+<p>
+Review and test your changes as much as possible. Check the
+differences from the previous version repeatedly
+(<prgn>interdiff</prgn> and <prgn>debdiff</prgn> are useful tools for
+this).
When packaging the fix, keep the following points in mind:
<list>
<item>Make sure you target the right distribution in your
- debian/changelog. For stable this is stable-security and for
- testing this is testing-security. Do not target
- <em>distribution</em>-proposed-updates!
+ <file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
+ testing this is <tt>testing-security</tt>, and for the previous
+ stable release, this is <tt>oldstable-security</tt>. Do not target
+ <var>distribution</var>-proposed-updates!
<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
- --compare-versions</tt>. For testing, this means there must be
- a greater version in unstable. If there is none yet (for example,
- if testing and unstable have the same version) you must upload a
+ --compare-versions</tt>. For <em>testing</em>, there must be
+ a higher version in <em>unstable</em>. If there is none yet (for example,
+ if <em>testing</em> and <em>unstable</em> have the same version) you must upload a
new version to unstable first.
<item>Do not make source-only uploads if your package has any
binary-all packages (do not use the <tt>-S</tt> option to
- <prgn>dpkg-buildpackage</prgn>). The buildd infrastructure will
+ <prgn>dpkg-buildpackage</prgn>). The <prgn>buildd</prgn> infrastructure will
not build those. This point applies to normal package uploads as
well.
- <item>Always build with full source (use the <tt>-sa</tt> option
- for <prgn>dpkg-buildpackage</prgn>).
+ <item>If the upstream source has been uploaded to
+ security.debian.org before (by a previous security update), build
+ the upload without the upstream source (<tt>dpkg-buildpackage
+ -sd</tt>). Otherwise, build with full source
+ (<tt>dpkg-buildpackage -sa</tt>).
- <item>Be sure to use the exact same .orig.tar.gz as used in the
+ <item>Be sure to use the exact same <file>*.orig.tar.gz</file> as used in the
normal archive, otherwise it is not possible to move the security
fix into the main archives later.
exactly meet the team's requirements, it will cause many problems and
delays in dealing with the unwanted upload.
<p>
-Once you have created and tested the new package, and it has been
+<em>DO NOT</em> 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
+is already installed into the archive, the security update will be
+rejected by the archive system. That way, the stable distribution
+will end up without a security update for this package instead.
+<p>
+Once you have created and tested the new package and it has been
approved by the security team, it needs to be uploaded so that it can
be installed in the archives. For security uploads, the place to
upload to is
<p>
If a member of the security team accepts a package, it will be
installed on security.debian.org as well as the proper
-<em>distribution</em>-proposed-updates on ftp-master or in the non-US
+<var>distribution</var>-proposed-updates on ftp-master or in the non-US
archive.
<sect1 id="upload-bugfix">When bugs are closed by new uploads
notification that your updated package has been installed into the
archive, you can and should close the bug in the BTS.
<p>
-If you are using a new version of <package>dpkg-dev</package> and you do
-your changelog entry properly, the archive maintenance software will close
-the bugs automatically. All you have to do is follow a certain syntax in
-your <file>debian/changelog</file> file:
+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>
+file, following a certain syntax, and the archive maintenance software
+will close the bugs for you. For example:
+
<example>
acme-cannon (3.1415) unstable; urgency=low
one of the most concise and easiest to integrate with the text of the
<file>changelog</file>.
<p>
-If you want to close bugs the old fashioned, manual way, it is usually
-sufficient to mail the <file>.changes</file> file to
+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>.
- <sect1 id="lintian-reports">Lintian reports
- <p>
-You should periodically get the new <package>lintian</package> from
-`unstable' and check over all your packages. Alternatively you can
-check for your maintainer email address at the <url id="&url-lintian;"
-name="online lintian report">. That report, which is updated
-automatically, contains <prgn>lintian</prgn> reports against the
-latest version of the distribution (usually from 'unstable') using the
-latest <package>lintian</package>.
<chapt id="best-pkging-practices">
<heading>Best Packaging Practices</heading>
<p>
-Debian's quality is largely due to its Policy that all packages
-follow. But it's also because we accumulated years of experience
-in packaging; very talented people created great tools to make
-good packages without much troubles.
+Debian's quality is largely due to the <url id="&url-debian-policy;"
+name="Debian Policy">, which defines explicit baseline requirements
+which all Debian packages must fulfill. Yet there is also a shared
+history of experience which goes beyond the Debian Policy, an
+accumulatation of years of experience in packaging. Many very
+talented people have created great tools, tools which help you, the
+Debian maintainer, create and maintain excellent packages.
<p>
-This chapter provides the best known solutions to common problems
-faced during packaging. It also lists various advice collected on
-several mailing lists. By following them, you will make Debian's quality
-even better.
-
- <sect id="packaging-tools">
- <heading>Packaging tools and common cases</heading>
+This chapter provides some best practices for Debian developers. All
+recommendations are merely that, and are not requirements or policy.
+These are just some subjective hints, advice and pointers collected
+from Debian developers. Feel free to pick and choose whatever works
+best for you.
+
+ <sect id="bpp-debian-rules">
+ <heading>Best practices for <file>debian/rules</file></heading>
+ <p>
+The following recommendations apply to the <file>debian/rules</file>
+file. Since <file>debian/rules</file> controls the build process and
+selects the files which go into the package (directly or indirectly),
+it's usually the file maintainers spend the most time on.
<sect1 id="helper-scripts">Helper scripts
<p>
-To help you in your packaging effort, you can use helper scripts.
-The best scripts available are provided by <package>debhelper</package>.
-With <prgn>dh_make</prgn> (package <package>dh-make</package>), you can
-generate in a few seconds a package that is mostly ready. However that
-apparent simplicity is hiding many things done by the helper scripts.
-You have to know what is done by them, that's why you are strongly
-encouraged to read the corresponding manual pages, starting with
-<tt>debhelper(1)</tt>. That's required because you'll have to
-understand what is going on to be able to use them wisely and to
-fix bugs in a pretty way.
- <p>
-debhelper is very useful because it lets you follow the latest Debian policy
-without doing many modifications since the changes that can be automated are
-almost always automatically done by a debhelper script. Furthermore it
-offers enough flexibility to be able to use it in conjunction with
-some hand crafted shell invocations within the <file>rules</file> file.
- <p>
-You can however decide to not use any helper script, and still write
-some very good <file>rules</file> file. Many examples are available
-at <url id="&url-rules-files;">.
+The rationale for using helper scripts in <file>debian/rules</file> is
+that lets maintainers use and share common logic among many packages.
+Take for instance the question of installing menu entries: you need to
+put the file into <file>/usr/lib/menu</file>, and add commands to the
+maintainer scripts to register and unregister the menu entries. Since
+this is a very common thing for packages to do, why should each
+maintainer rewrite all this on their own, sometimes with bugs? Also,
+supposing the menu directory changed, every package would have to be
+changed.
+ <p>
+Helper scripts take care of these issues. Assuming you comply with
+the conventions expected by the helper script, the helper takes care
+of all the details. Changes in policy can be made in the helper
+script, then packages just need to be rebuilt with the new version of
+the helper and no other changes.
+ <p>
+<ref id="tools"> contains a couple of different helpers. The most
+common and best (in our opinion) helper system is
+<package>debhelper</package>. Previous helper systems, such as
+<package>debmake</package>, were "monolithic": you couldn't pick and
+choose which part of the helper you found useful, but had to use the
+helper to do everything. <package>debhelper</package>, however, is a
+number of seperate little <prgn>dh_*</prgn> programs. For instance,
+<prgn>dh_installman</prgn> installs and compresses manpages,
+<prgn>dh_installmenu</prgn> installs menu files, and so on. Thus, it
+offers enough flexibility to be able to use the little helper scripts,
+where useful, in conjunction with hand-crafted commands in
+<file>debian/rules</file>.
+ <p>
+You can get started with <package>debhelper</package> by reading
+<manref name="debhelper" section="1">, and looking at the examples
+that come with the package. <prgn>dh_make</prgn>, from the
+<package>dh-make</package> package (see <ref id="dh-make">), can be
+used to convert a "vanilla" source package to a
+<package>debhelper</package>ized package. This shortcut, though,
+should not convince you that you do not need to bother understanding
+the individual <prgn>dh_*</prgn> helpers. If you are going to use a
+helper, you do need to take the time to learn to use that helper, to
+learn its expectations and behavior.
+ <p>
+Some people feel that vanilla <file>debian/rules</file> files are
+better, since you don't have to learn the intricies of any helper
+system. This decision is completely up to you. Use what works for
+you. Many examples of vanilla <file>debian/rules</file> files are
+available at <url id="&url-rules-files;">.
+
+
+ <sect1 id="multiple-patches">
+ <heading>Patching source versus patching at build time</heading>
+ <p>
+Big, complex packages may have many bugs that you need to deal with.
+If you correct a number of bug directly in the source, if you're not
+careful, it can get hard to differentiate the various patches that you
+applied. It can get quite messy when you have to update the package
+to a new upstream version which integrates some of the fixes (but not
+all). You can't take the total set of diffs (e.g., from
+<file>.diff.gz</file>) and work out which patch sets to back out as a
+unit as bugs are fixed upstream.
+ <p>
+One good solution is to keep separate patches under the
+<file>debian</file> directory and apply the patches at build time. The
+<package>dbs</package> package provides an convenient means for
+applying patches at build time (and unapplying them at clean time).
+<package>dbs</package> also provides facilities for creating the
+patches and keeping track of what they are for. As always when using
+maintainer tools, you'll have to read the accompanying documentation.
+The package <package>hello-dbs</package> is a simple example that
+demonstrates how to use <package>dbs</package>.
+
+
+ <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
+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
+permutations of the various packages, ensuring that you have the
+inter-package dependancies 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
+this using an hand-crafted <file>debian/rules</file> file.
+
+<!-- &FIXME; Find a good debhelper example with multile configure/make
+ cycles -->
+ </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 shbang 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 existance of a command, you should use
+something like
+<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
+
+If you don't wish to hardcode 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. 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, although that is probably not something
+that will cause a problem.
+
+
+ <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>
+For consistency and aesthetics, you should capitalize the first letter
+of the Synopsis. Don't put a full stop (period) at the end. The
+description itself should 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 homepage to the
+package description in <file>debian/control</file>, and a link to a
+screenshot, if one is handy. This information should be added at the
+end of description, using the following format:
+
+<example> .
+ Homepage: http://some-project.some-place.org/
+ Screenshot: 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.
+ </sect1>
+ </sect>
<!--
<sect1 id="pkg-mgmt-cvs">Managing a package with CVS
via CVS (debian/rules refresh).
-->
- <sect1 id="multiple-patches">Package with multiple patches
- <p>
-Big packages tend to have many upstream bugs that you want to fix within
-the Debian package. If you just correct the bug in the source, all the
-fixes are directly integrated in the <file>.diff.gz</file> file and you
-can't easily differentiate the various patches that you applied. It gets
-very messy when you have to update the package to a new upstream version
-which integrates some of the fixes (but not all).
- <p>
-The good solution is to keep separate patches within the
-<file>debian/patches</file> directory and to apply them on the fly at
-build time. The package <package>dbs</package> provides an
-implementation of such a system, you just have to build-depend on dbs to
-be able to use its functionalities. The package
-<package>hello-dbs</package> is a simple example that demonstrates how to
-use <package>dbs</package>.
- <p>
-Additionally, dbs provides facilities to create the patches and to keep
-track of what they are for.
- <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
-vim-* packages) or to make several small packages instead of a big one
-(it's interesting if the user doesn't need all the packages and can thus
-save some disk space).
+ <sect id="bpp-config-mgmt">
+ <heading>Configuration management with <package>debconf</package></heading>
+
<p>
-The second case can be easily managed by <prgn>dh_install</prgn> (from
-<package>debhelper</package>) to move files from the build directory to
-the package's temporary trees.
+<package>Debconf</package> is a configuration management system which
+can be used by all the various packaging scripts
+(<file>postinst</file> mainly) to request feedback from the user
+concerning how to configure the package. Direct user interactions must
+now be avoided in favor of <package>debconf</package>
+interaction. This will enable non-interactive installations in the
+future.
<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 this with an
-hand crafted rules file.
-<!-- &FIXME; Find a good debhelper example with multile configure/make
- cycles -->
+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.
+It is something that you must read if you decide to use debconf.
+ </sect>
- <sect1 id="handling-debconf-translations">Handling debconf translations
- <p>
-Like porters, translators have a difficult task. Since they work on many
-packages, they cannot keep track of every change in packages in order to
-be informed when a translated string is outdated. Fortunately
-<package>debconf</package> can automatically report outdated translations,
-if package maintainers follow some basic guidelines described below.
- <p>
-Translators can use <prgn>debconf-getlang</prgn> (package
-<package>debconf-utils</package>) to write a <file>templates.xx</file>
-file containing both English and localized fields (where <em>xx</em> is
-the language code, may be followed by a country code). This file can be
-put into the <file>debian</file> subdirectory without any change.
- <p>
-When building a binary package, <file>debian/templates.xx</file> files are
-merged along with <file>debian/templates</file> to generate the
-<file>templates</file> file contained in the binary package. This is
-automatically done by <prgn>dh_installdebconf</prgn> (package
-<package>debhelper</package>). If you do not use debhelper, you can
-do the same with <prgn>debconf-mergetemplate</prgn>
-(package <package>debconf-utils</package>).
- <p>
-When the package maintainer needs to update the templates file, they only
-change <file>debian/templates</file>. When English strings in this file
-and in <file>debian/templates.xx</file> differ, translators do know that
-their translation is outdated.
- <p>
-Please see the page about
-<url id="&url-debconf-l10n-help;" name="localizing debconf templates files">
-at the Debian web site, it contains more detailed instructions, including a
-full example.
+ <sect id="bpp-i18n">
+ <heading>Internationalization</heading>
+
+ <sect1 id="bpp-i18n-debconf">
+ <heading>Handling debconf translations</heading>
+ <p>
+Like porters, translators have a difficult task. They work on many
+packages and must collaborate with many different
+maintainers. Moreover, most of the time, they are not native English
+speakers, so you may need to be particularly patient with them.
+ <p>
+The goal of <package>debconf</package> was to make packages
+configuration easier for maintainers and for users. Originally,
+translation of debconf templates was handled with
+<prgn>debconf-mergetemplate</prgn>. However, that technique is now
+deprecated; the best way to accomplish <package>debconf</package>
+internationalization is by using the <package>po-debconf</package>
+package. This method is easier both for maintainer and translators;
+transition scripts are provided.
+ <p>
+Using <package>po-debconf</package>, the translation is stored in
+<file>po</file> files (drawing from <prgn>gettext</prgn> translation
+techniques). Special template files contain the original messages and
+mark which fields are translatable. When you change the value of a
+translatable field, by calling <prgn>debconf-updatepo</prgn>, the
+translation is marked as needing attention from the translators. Then,
+at build time, the <prgn>dh_installdebconf</prgn> program takes care
+of all the needed magic to add the template along with the up-to-date
+translations into the binary packages. Refer to the <manref
+name="po-debconf" section="7"> manual page for details.
+ </sect1>
+
+ <sect1 id="bpp-i18n-docs">
+ <heading>Internationalized documentation</heading>
+ <p>
+Internationalizing documentation is crucial for users, but a lot of
+labor. There's no way to eliminate all that work, but you can make things
+easier for translators.
+ <p>
+If you maintain documentation of any size, its easier for translators
+if they have access to a source control system. That lets translators
+see the differences between two versions of the documentation, so, for
+instance, they can see what needs to be retranslated. It is
+recommended that the translated documentation maintain a note about
+what source control revision the translation is based on. An
+interesting system is provided by <url id="&url-i18n-doc-check;"
+name="doc-check"> in the <package>boot-floppies</package> package,
+which shows an overview of the translation status for any given
+language, using structured comments for the current revision of the
+file to be translated and, for a translated file, the revision of the
+original file the translation is based on. You might wish to adapt
+and provide that in your CVS area.
+ <p>
+If you maintain XML or SGML documentation, we suggest that you isolate
+any language-independant information and define those as entities in a
+separate file which is included by all the different
+translations. This makes it much easier, for instance, to keep URLs
+up-to-date across multiple files.
+ </sect1>
+ </sect>
- <sect id="specific-practices">
- <heading>Specific packaging practices</heading>
+ <sect id="bpp-common-situations">
+ <heading>Common packaging situations</heading>
<!--
<sect1 id="bpp-kernel">Kernel modules/patches
/etc/modutils/ for module configuration.
-->
- <sect1 id="bpp-autotools">Packages using autoconf/automake
- <p>
-Some very good packaging practices for packages using autoconf and/or
-automake have been synthetized in &file-bpp-autotools;. You're strongly
-encouraged to read this file and to follow the given recommandations.
+ <sect1 id="bpp-autotools">
+ <heading>Packages using
+ <prgn>autoconf</prgn>/<prgn>automake</prgn></heading>
+ <p>
+Keeping <prgn>autoconf</prgn>'s <file>config.sub</file> and
+<file>config.guess</file> files up-to-date is critical for porters,
+especially on more volatile architectures. Some very good packaging
+practices for any package using <prgn>autoconf</prgn> and/or
+<prgn>automake</prgn> have been synthesized in
+&file-bpp-autotools;. You're strongly encouraged to read this file and
+to follow the given recommendations.
<sect1 id="bpp-libraries">Libraries
Libraries are always difficult to package for various reasons. The policy
imposes many constraints to ease their maintenance and to make sure
upgrades are as simple as possible when a new upstream version comes out.
-A breakage in a library can result in dozens of dependent packages to
-break...
+A breakage in a library can result in dozens of dependent packages
+breaking.
<p>
Good practices for library packaging have been grouped in
<url id="&url-libpkg-guide;" name="the library packaging guide">.
- <sect1 id="bpp-other-specific-practices">Other specific packages
+ <sect1 id="bpp-other">Specific types of packages
<p>
-Several subsets of packages have special sub-policies and corresponding
-packaging rules and practices:
+Several specific types of packages have special sub-policies and
+corresponding packaging rules and practices:
<list>
<item>
-Perl related packages have a <url name="perl policy" id="&url-perl-policy;">,
-some examples of packages following that policy are
-<package>libdbd-pg-perl</package> (binary perl module) or
+Perl related packages have a <url name="Perl policy"
+id="&url-perl-policy;">, some examples of packages following that
+policy are <package>libdbd-pg-perl</package> (binary perl module) or
<package>libmldbm-perl</package> (arch independent perl module).
<item>
-Python related packages have their python policy:
-&file-python-policy; (in the python package).
+Python related packages have their python policy; see
+&file-python-policy; in the <package>python</package> package.
<item>
Emacs related packages have the <url id="&url-emacs-policy;"
name="emacs policy">.
Java related packages have their <url id="&url-java-policy;"
name="java policy">.
<item>
-Ocaml related packages have their ocaml policy: &file-ocaml-policy; (in
-the <package>ocaml</package> package). A good example is the <package>camlzip</package>
-source package.
+Ocaml related packages have their own policy, found in
+&file-ocaml-policy; from the <package>ocaml</package> package. A good
+example is the <package>camlzip</package> source package.
+ <item>
+Packages providing XML or SGML DTDs should conform to the
+recommendations found in the <package>sgml-base-doc</package>
+package.
+ <item>
+Lisp packages should register themselves with
+<package>common-lisp-controller</package>, about which see
+&file-lisp-controller;.
</list>
-
- <sect id="config-mgmt">
- <heading>Configuration management</heading>
-
- <sect1 id="config-wise-debconf">The wise use of debconf
- <p>
-Debconf is a configuration management system, it is used by all the
-various packaging scripts (postinst mainly) to request feedback from the
-user concerning how to configure the package. Direct user interactions
-must now be avoided in favor of debconf interaction. This will enable
-non-interactive installations in the future.
- <p>
-Debconf is a great tool but it is often badly used ... many common mistakes
-are listed in the <manref name="debconf-devel" section="8"> man page.
-It is something that you must read if you decide to use debconf.
+ </sect1>
+ </sect>
<!--
<sect1 id="custom-config-files">Custom configuration files
sympa may be an example package
-->
- <sect id="misc-advice">
- <heading>Miscellaneous advice</heading>
-
- <sect1 id="writing-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 usually the first information
-available to the user before they install it. As such, it should
-provide all the required information to let him decide whether
-to install the package.
- <p>
-For example, apart from the usual description that you adapt from the
-upstream <file>README</file>, you should include the URL of the
-web site if there's any. If the package is not yet considered stable
-by the author, you may also want to warn the user that the
-package is not ready for production use.
- <p>
-For consistency and for an aesthetic concern, you should capitalize the
-first letter of the description.
- <p>
-Last but not least, since the first user impression is based on
-that description, you should be careful to avoid English
-mistakes. Ensure that you spell check it.
-<prgn>ispell</prgn> has a special option (<tt>-g</tt>) for that:
-<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;.
simply creating and maintaining packages.
<p>
As a volunteer organization, Debian relies on the discretion of its
-members in choosing what they want to work on, and choosing what is
+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
Even though there is a dedicated group of people for Quality
Assurance, QA duties are not reserved solely for them. You can
participate in this effort by keeping your packages as bug-free as
-possible, and as lintian-clean (see <ref id="lintian-reports">) as
+possible, and as lintian-clean (see <ref id="lintian">) as
possible. If you do not find that possible, then you should consider
orphaning some of your packages (see <ref
id="orphaning">). Alternatively, you may ask the help of other people
for help on &email-debian-qa; or &email-debian-devel;). At the same
time, you can look for co-maintainers (see <ref id="collaborative-maint">).
- <sect1 id="qa-bsp">Bug Squashing Parties
+ <sect1 id="qa-bsp">Bug squashing parties
<p>
From time to time the QA group organizes bug squashing parties to get rid of
as many problems as possible. They are announced on &email-debian-devel-announce;
the BTS.
<p>
People participating in the party have special rules for NMU, they can
-NMU withour prior notice if they upload their NMU to
+NMU without prior notice if they upload their NMU to
DELAYED/3-day at least. All other NMU rules applies as usually, they
should send the patch of the NMU in the BTS (in one of the open bugs
fixed by the NMU or in a new bug tagged fixed). They should
-also respect the maintainer's wishes if he expressed some.
+also respect the maintainer's wishes if he expressed some.
+ <p>
+If someone doesn't feel confident with an NMU, he should just send a patch
+to the BTS. It's far better than a broken NMU.
<sect id="mia-qa">Dealing with unreachable maintainers
<p>
must build and test the package on your own system before uploading.
<p>
You can not simply upload a binary <file>.deb</file> from the sponsoree. In
-theory, you should only ask only for the diff file, and the location of the
+theory, you should only ask for the diff file and the location of the
original source tarball, and then you should download the source and apply
the diff yourself. In practice, you may want to use the source package
built by your sponsoree. In that case, you have to check that they haven't
<p>
Once the package meets Debian standards, build the package with
<example>dpkg-buildpackage -us -uc</example> and sign it
-with <example>debsign -m <your-email-addr> <changes-file></example>
+with <example>debsign -m"<var>FULLNAME</var> <var>email-addr</var>" <var>changes-file</var></example>
before uploading it to the incoming directory.
<p>
The Maintainer field of the <file>control</file> file and the
Most of the descriptions of these packages come from the actual
package descriptions themselves. Further information can be found in
the package documentation itself. You can also see more info with the
-command <tt>apt-cache show <package-name></tt>.
+command <tt>apt-cache show <package-name></tt>.</p>
+ <sect id="tools-core">
+ <heading>Core tools</heading>
+ <p>
+The following tools are pretty much required for any maintainer.</p>
- <sect id="dpkg-dev">
+ <sect1 id="dpkg-dev">
<heading><package>dpkg-dev</package>
<p>
<package>dpkg-dev</package> contains the tools (including
functionality required to create and manipulated packages; as such,
they are required for any Debian maintainer.
-
- <sect id="lintian">
- <heading><package>lintian</package>
- <p>
-<package>Lintian</package> dissects Debian packages and reports bugs
-and policy violations. It contains automated checks for many aspects
-of Debian policy as well as some checks for common errors. The use of
-<package>lintian</package> has already been discussed in <ref
-id="upload-checking"> and <ref id="lintian-reports">.
-
-
- <sect id="debconf">
+ <sect1 id="debconf">
<heading><package>debconf</package></heading>
<p>
<package>debconf</package> provides a consistent interface to
<package>debconf-doc</package> package.
<p>
Many feel that this system should be used for all packages requiring
-interactive configuration. <package>debconf</package> is not
-currently required by Debian Policy, however, that may change in the
-future.
+interactive configuration; see <ref id="bpp-config-mgmt">.
+<package>debconf</package> is not currently required by Debian Policy,
+but that may change in the future.
+ </sect1>
+
+ <sect1 id="fakeroot">
+ <heading><package>fakeroot</package>
+ <p>
+<package>fakeroot</package> simulates root privileges. This enables
+you to build packages without being root (packages usually want to
+install files with root ownership). If you have
+<package>fakeroot</package> installed, you can build packages as a
+user: <tt>dpkg-buildpackage -rfakeroot</tt>.
+ </sect1>
+ </sect>
+
+ <sect id="tools-lint">
+ <heading>Package lint tools</heading>
<p>
+According to the Free On-line Dictionary of Computing (FOLDOC), `lint'
+is "a Unix C language processor which carries out more thorough checks
+on the code than is usual with C compilers." Package lint tools help
+package maintainers by automatically finding common problems and
+policy violations with their packages.</p>
+
+ <sect1 id="lintian">
+ <heading><package>lintian</package></heading>
+ <p>
+<package>lintian</package> dissects Debian packages and emits
+information on bugs
+and policy violations. It contains automated checks for many aspects
+of Debian policy as well as some checks for common errors.
+ <p>
+You should periodically get the newest <package>lintian</package> from
+`unstable' and check over all your packages. Notice that the <tt>-i</tt>
+option provides detailed explanations of what each error or warning means,
+what is its basis in Policy, and commonly how you can fix the problem.
+ <p>
+Refer to <ref id="upload-checking"> for more information on how and when
+to use Lintian.
+ <p>
+You can also see a summary of all problems reported by Lintian on your
+packages at <url id="&url-lintian;">. Those reports contain the latest
+<prgn>lintian</prgn> output on the whole development distribution
+("unstable").
+ </sect1>
+ <sect1 id="linda">
+ <heading><package>linda</package></heading>
+ <p>
+<package>linda</package> is another package linter. It is similar to
+<package>lintian</package> but has a different set of checks. Its
+written in Python rather than Perl.</p>
+ </sect1>
+ </sect>
+
+ <sect id="tools-helpers">
+ <heading>Helpers for <file>debian/rules</file></heading>
+ <p>
+Package building tools make the process of writing
+<file>debian/rules</file> files easier. See <ref id="helper-scripts">
+for more information on why these might or might not be desired.
- <sect id="debhelper">
- <heading><package>debhelper</package>
+ <sect1 id="debhelper">
+ <heading><package>debhelper</package></heading>
<p>
<package>debhelper</package> is a collection of programs that can be
used in <file>debian/rules</file> to automate common tasks related to
There are a number of little <package>debhelper</package> add-on
packages, too transient to document. You can see the list of most of
them by doing <tt>apt-cache search ^dh-</tt>.
+ </sect1>
-
- <sect id="debmake">
- <heading><package>debmake</package>
+ <sect1 id="debmake">
+ <heading><package>debmake</package>
<p>
<package>debmake</package>, a pre-cursor to
<package>debhelper</package>, is a less granular
The consensus is that <package>debmake</package> is now deprecated in
favor of <package>debhelper</package>. However, it's not a bug to use
<package>debmake</package>.
+ </sect1>
+ <sect1 id="dh-make">
+ <heading><package>dh-make</package>
+ <p>
+The <package/dh-make/ package contains <prgn/dh_make/, a program that
+creates a skeleton of files necessary to build a Debian package out of
+a source tree. As the name suggests, <prgn/dh_make/ is a rewrite of
+<package/debmake/ and its template files use dh_* programs from
+<package/debhelper/.
+ <p>
+While the rules files generated by <prgn/dh_make/ are in general a
+sufficient basis for a working package, they are still just the groundwork:
+the burden still lies on the maintainer to finely tune the generated files
+and make the package entirely functional and Policy-compliant.
+ </sect1>
- <sect id="yada">
- <heading><package>yada</package>
+ <sect1 id="yada">
+
<heading><package>yada</package>
<p>
<package>yada</package> is another packaging helper tool. It uses a
<file>debian/packages</file> file to auto-generate
Note that <package>yada</package> is called "essentially unmaintained"
by it's own maintainer, Charles Briscoe-Smith. As such, it can be
considered deprecated.
+ </sect1>
-
- <sect id="equivs">
- <heading><package>equivs</package>
+ <sect1 id="equivs">
+ <heading><package>equivs</package>
<p>
<package>equivs</package> is another package for making packages. It
is often suggested for local use if you need to make a package simply
to fulfill dependencies. It is also sometimes used when making
``meta-packages'', which are packages whose only purpose is to depend
-on other packages.
+on other packages.</p>
+ </sect1>
+ </sect>
- <sect id="cvs-buildpackage">
- <heading><package>cvs-buildpackage</package>
+
+ <sect id="tools-builders">
+ <heading>Package builders</heading>
+ <p>
+The following packages help with the package building process, general
+driving <prgn>dpkg-buildpackage</prgn> as well as handling supporting
+tasks.</p>
+
+ <sect1 id="cvs-buildpackage">
+ <heading><package>cvs-buildpackage</package>
<p>
<package>cvs-buildpackage</package> provides the capability to inject
or import Debian source packages into a CVS repository, build a Debian
<p>
These utilities provide an infrastructure to facilitate the use of CVS
by Debian maintainers. This allows one to keep separate CVS branches
-of a package for <em>stable</em>, <em>unstable</em>, and possibly
+of a package for <em>stable</em>, <em>unstable</em> and possibly
<em>experimental</em> distributions, along with the other benefits of
a version control system.
+ </sect1>
-
- <sect id="dupload">
- <heading><package>dupload</package>
+ <sect1 id="debootstrap">
+ <heading><package>debootstrap</package></heading>
+ <p>
+The <package>debootstrap</package> package and script allows you to
+"bootstrap" a Debian base system into any part of your file-system.
+By "base system", we mean the bare minimum of packages required to
+operate and install the rest of the system.
<p>
+Having a system like this can be useful in many ways. For instance,
+you can <prgn>chroot</prgn> into it if you want to test your build
+depends. Or, you can test how your package behaves when installed
+into a bare base system. Chroot builders use this package, see below.
+ </sect1>
+
+ <sect1 id="pbuilder">
+ <heading><package>pbuilder</package></heading>
+ <p>
+<package>pbuilder</package> constructs a chrooted system, and builds a
+package inside the chroot. It is very useful to check that a package's
+build-dependencies are correct, and to be sure that unnecessary and
+wrong build dependencies will not exist in the resulting package.</p>
+ <p>
+A related package is <package>pbuilder-uml</package>, which goes even
+further build doing the build within User-mode-linux.</p>
+ </sect1>
+
+ <sect1 id="sbuild">
+ <heading><package>sbuild</package></heading>
+ <p>
+<package>sbuild</package> is another automated builder. It can use
+chrooted environments as well. It can be used stand-alone, or as part
+of a networked, distributed build environment. As the latter, it is
+part of the system used by porters to build binary packages for all
+the available architectures. See <ref id="buildd"> for more
+information, and <url id="&url-buildd;"> to see the system in
+action.</p>
+ </sect1>
+ </sect>
+
+ <sect id="uploaders">
+ <heading>Package uploaders</heading>
+ <p>
+The following packages help automate or simplify the process of
+uploading packages into the official archive.</p>
+
+ <sect1 id="dupload">
+ <heading><package>dupload</package></heading>
+ <p>
<package>dupload</package> is a package and a script to automatically
upload Debian packages to the Debian archive, to log the upload, and
to send mail about the upload of a package. You can configure it for
new upload locations or methods.
+ </sect1>
-
- <sect id="dput">
- <heading><package>dput</package>
- <p>
+ <sect1 id="dput">
+ <heading><package>dput</package></heading>
+ <p>
The <package>dput</package> package and script does much the same
thing as <package>dupload</package>, but in a different way. It has
some features over <package>dupload</package>, such as the ability to
check the GnuPG signature and checksums before uploading, and the
possibility of running <prgn>dinstall</prgn> in dry-run mode after the
upload.
+ </sect1>
+ </sect>
-
- <sect id="fakeroot">
- <heading><package>fakeroot</package>
- <p>
-<package>fakeroot</package> simulates root privileges. This enables
-you to build packages without being root (packages usually want to
-install files with root ownership). If you have
-<package>fakeroot</package> installed, you can build packages as a
-user: <tt>dpkg-buildpackage -rfakeroot</tt>.
-
-
- <sect id="debootstrap">
- <heading><package>debootstrap</package>
- <p>
-The <package>debootstrap</package> package and script allows you to
-"bootstrap" a Debian base system into any part of your file-system.
-By "base system", we mean the bare minimum of packages required to
-operate and install the rest of the system.
- <p>
-Having a system like this can be useful in many ways. For instance,
-you can <prgn>chroot</prgn> into it if you want to test your build
-depends. Or, you can test how your package behaves when installed
-into a bare base system.
-
-
- <sect id="pbuilder">
- <heading><package>pbuilder</package>
+ <sect id="tools-maint-automate">
+ <heading>Maintenance automation</heading>
<p>
-<package>pbuilder</package> constructs a chrooted system, and builds
-a package inside the chroot. It is very useful to check that
-a package's build-dependencies are correct, and to be sure that
-unnecessary and wrong build dependencies will not exist in the
-resulting package.
-
+The following tools help automate different maintenance tasks, from
+adding changelog entries or signature lines, looking up bugs in Emacs,
+to making use of the newest and official use of
+<file>config.sub</file>.</p>
- <sect id="devscripts">
- <heading><package>devscripts</package>
- <p>
-<package>devscripts</package> is a package containing a few wrappers
+ <sect1 id="devscripts">
+ <heading><package>devscripts</package></heading>
+<package>devscripts</package> is a package containing wrappers
and tools which are very helpful for maintaining your Debian
packages. Example scripts include <prgn>debchange</prgn> and
<prgn>dch</prgn>, which manipulate your <file>debian/changelog</file>
file from the command-line, and <prgn>debuild</prgn>, which is a
wrapper around <prgn>dpkg-buildpackage</prgn>. The <prgn>bts</prgn>
utility is also very helpful to update the state of bug reports on the
-command line, as is <prgn>uscan</prgn> to watch for new upstream
-versions of your packages. Check the <tt>devscripts(1)</tt> manual
-page for a complete list of available scripts.
-
+command line. <prgn>uscan</prgn> can be used to watch for new upstream
+versions of your packages. The <prgn>debrsign</prgn> can be used to
+remotely sign a package prior to upload, which is nice when the
+machine you build the package on is different from where your GPG keys
+are.</p>
+ <p>
+See the <manref name="devscripts" section="1"> manual page for a
+complete list of available scripts.</p>
+ </sect1>
- <sect id="dpkg-dev-el">
- <heading><package>dpkg-dev-el</package>
- <p>
+ <sect1 id="dpkg-dev-el">
+ <heading><package>dpkg-dev-el</package></heading>
<package>dpkg-dev-el</package> is an Emacs lisp package which provides
assistance when editing some of the files in the <file>debian</file>
directory of your package. For instance, when editing
<file>debian/changelog</file>, there are handy functions for
-finalizing a version and listing the package's current bugs.
+finalizing a version and listing the package's current bugs.</p>
+ </sect1>
+ </sect>
- <sect id="debget">
- <heading><package>debget</package>
- <p>
-<package>debget</package> is a package containing a convenient script
-which can be helpful in downloading files from the Debian archive.
-You can use it to download source packages, for instance (although
-<tt>apt-get source <package-name></tt> does pretty much the same
-thing).
+ <sect id="tools-porting">
+ <heading>Porting tools</heading>
+ <p>
+The following tools are helpful for porters and for
+cross-compilation.</p>
+
+ <sect1 id="quinn-diff">
+ <heading><package>quinn-diff</package>
+ <p>
+<package>quinn-diff</package> is used to locate the differences from
+one architecture to another. For instance, it could tell you which
+packages need to be ported for architecture <var>Y</var>, based on
+architecture <var>X</var>.
+ <sect1 id="dpkg-cross">
+ <heading><package>dpkg-cross</package>
+ <p>
+<package>dpkg-cross</package> is a tool for installing libraries and
+headers for cross-compiling in a way similar to
+<package>dpkg</package>. Furthermore, the functionality of
+<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
+enhanced to support cross-compiling.
+ </sect1>
+ </sect>
<!-- FIXME: add the following
- dpkg-awk
alien
dpkg-repack
+ debsums
+ debiandoc-sgml, debiandoc-sgml-doc
+ debian-keyring
+
+questionable:
+ ucf
+ dpkg-awk
grep-dctrl
+ debview
+ d-shlibs
+ wajig
+ magpie
+ apt-dpkg-ref
+ apt-show-source
+ apt-show-versions
+ pdbv
+ epm
+
+rejected:
+ debaux: too new, unmaintained?
+ dh-make-perl: too new, unmaintained?
-->
-
+ </appendix>
</book>
</debiandoc>
~ianmdlvl / developers-reference.git / blobdiff