<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.151 $">
+ <!entity cvs-rev "$Revision: 1.162 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
]>
<debiandoc>
-<!--
- TODO:
- - bugs in upstream versions should be reported upstream!
- - add information on how to get accounts on different architectures
- - talk about CVS access, other ways to submit problems
- - add information on how you can contribute w/o being an official
- developer
- - "official port maintainer" ? (cf. glibc-pre2.1)
- -->
-
<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>
<copyright>
<copyrightsummary>
-copyright © 1998—2002 Adam Di Carlo</copyrightsummary>
+copyright © 1998—2003 Adam Di Carlo</copyrightsummary>
<copyrightsummary>
copyright © 2002 Raphaël Hertzog</copyrightsummary>
<copyrightsummary>
if they respect themselves all the criteria);
</list>
<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 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>.
+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 overview"> gives some more information
+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>
<item>
CVS commits if the maintainer has setup a system to forward commit
notification to the PTS.
+
+ <tag><tt>ddtp</tt>
+ <item>
+Translations of descriptions or debconf templates
+submitted to the Debian Description Translation Project.
</taglist>
<sect1 id="pts-commands">The PTS email interface
<email>control@bugs.debian.org</email>
<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>upload-source</tt>: announce of a new source upload that
has been accepted
<item><tt>upload-binary</tt>: announce of a new binary-only upload (porting)
<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
+porting to these tools; see the package documentation or references for
full information.</p>
<sect2>
It is not OK to simply take over a package that you feel is neglected
— that would be package hijacking. You can, of course, contact the
current maintainer and ask them if you may take over the package.
-However, without their assent, you may not take over the package.
-Even if they ignore you, that is still not grounds to take over a
-package. If you really feel that a maintainer has gone AWOL (absent
-without leave), post a query to &email-debian-private;. You may also
-inform the QA group (cf. <ref id="mia-qa">).
+If you have reason to believe a maintainer has gone AWOL
+(absent without leave), see <ref id="mia-qa">.
+ <p>
+Generally, you may not take over the package without the assent of the
+current maintainer. Even if they ignore you, that is still not grounds to
+take over a package. Complaints about maintainers should be brought up on
+the developers' mailing list. If the discussion doesn't end with a positive
+conclusion, and the issue is of a technical nature, consider bringing it to
+the attention of the technical committee (see the <url name="technical
+committee web page" id="&url-tech-ctte;"> for more information).
<p>
If you take over an old package, you probably want to be listed as the
package's official maintainer in the bug system. This will happen
<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
+(<prgn>interdiff</prgn> from the <package>patchutils</package> package
+and <prgn>debdiff</prgn> from <package>devscripts</package> are useful tools for
this).
When packaging the fix, keep the following points in mind:
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
+accumulation 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>
<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 sep
erate little <prgn>dh_*</prgn> programs. For instance,
-<prgn>dh_installman</prgn> installs and compresses manpages,
+number of sep
arate little <prgn>dh_*</prgn> programs. For instance,
+<prgn>dh_installman</prgn> installs and compresses man pages,
<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
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
+better, since you don't have to learn the intricacies 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>
+ <heading>Separating your patches into multiple files</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
<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>.
+Unfortunately, the packaging system as such currently doesn't provide for
+separating the patches into several files. Nevertheless, there are ways to
+separate patches: the patch files are shipped within the Debian patch file
+(<file>.diff.gz</file>), usually within the <file>debian/</file> directory.
+The only difference is that they aren't applied immediately by dpkg-source,
+but by the <tt>build</tt> rule of <file>debian/rules</file>. Conversely,
+they are reverted in the <tt>clean</tt> rule.
+ <p>
+<prgn>dbs</prgn> is one of the more popular approaches to this. It does all
+of the above, and provides a facility for creating new and updating old
+patches. See the package <package>dbs</package> for more information and
+<package>hello-dbs</package> for an example.
+ <p>
+<prgn>dpatch</prgn> also provides these facilities, but it's intented to be
+even easier to use. See the package <package>dpatch</package> for
+documentation and examples (in <file>/usr/share/doc/dpatch</file>).
<sect1 id="multiple-binary">Multiple binary packages
<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>.
+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
this using an hand-crafted <file>debian/rules</file> file.
-<!-- &FIXME; Find a good debhelper example with multile configure/make
+<!-- &FIXME; Find a good debhelper example with multiple configure/make
cycles -->
</sect1>
</sect>
<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
+the maintainer script must have a bash sh-bang line. POSIX shell or
Bash are preferred to Perl, since they enable
<package>debhelper</package> to easily add bits to the scripts.
<p>
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
+If you need to check for the existence of a command, you should use
something like
<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
-If you don't wish to hardcode the path of the command in your
+If you don't wish to hard-code the path of the command in your
maintainer script, the following POSIX-compliant shell function may
help:
<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
+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/
- Screenshot: http://some-project.some-place.org/</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
<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>
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
+any language-independent 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.
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
+&file-bpp-autotools; from the <package>autotools-dev</package>
+package. You're strongly encouraged to read this file and
to follow the given recommendations.
Good practices for library packaging have been grouped in
<url id="&url-libpkg-guide;" name="the library packaging guide">.
+
+ <sect1 id="bpp-docs">Documentation
+ <p>
+Be sure to follow the <url id="&url-debian-policy;ch-docs.html"
+ name="Policy on documentation">.</p>
+ <p>
+If your package contains documentation built from XML or SGML, we
+recommend you not ship the XML or SGML source in the binary
+package(s). If users want the source of the documentation, they
+should retrieve the source package.</p>
+ <p>
+Policy specifies that documentation should be shipped in HTML format.
+We also recommend shipping documentation in PDF and plain text format if
+convenient and quality output is possible. However, it is generally
+not appropriate to ship plain text versions of documentation whose source
+format is HTML.</p>
+ <p>
+Major shipped manuals should register themselves with
+<package>doc-base</package> on installation. See the
+<package>doc-base</package> package documentation for more
+information.</p>
+
+
<sect1 id="bpp-other">Specific types of packages
<p>
Several specific types of packages have special sub-policies and
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>
-If you notice that a package is lacking maintenance, you should
-make sure the maintainer is active and will continue to work on
-his packages. Try contacting him yourself.
- <p>
-If you do not get a reply after a few weeks you should collect all
-useful information about this maintainer. Start by logging into
-the <url id="&url-debian-db;" name="Debian Developer's Database">
-and doing a full search to check whether the maintainer is on vacation
-and when they were last seen. Collect any important package names
-they maintain and any Release Critical bugs filed against them.
- <p>
-Send all this information to &email-debian-qa;, in order to let the
-QA people do whatever is needed.
<sect id="contacting-maintainers">Contacting other maintainers
<p>
email address.
+ <sect id="mia-qa">Dealing with inactive and/or unreachable maintainers
+ <p>
+If you notice that a package is lacking maintenance, you should
+make sure that the maintainer is active and will continue to work on
+their packages. It is possible that they are not active any more, but
+haven't registered out of the system, so to speak. On the other hand,
+it is also possible that they just need a reminder.
+ <p>
+The first step is to politely contact the maintainer, and wait for a
+response, for a reasonable time. It is quite hard to define "reasonable
+time", but it is important to take into account that real life is sometimes
+very hectic. One way to handle this would be send a reminder after two
+weeks.
+ <p>
+If the maintainer doesn't reply within four weeks (a month), one can
+assume that a response will probably not happen. If that happens, you
+should investigate further, and try to gather as much useful information
+about the maintainer in question as possible. This includes:
+ <p>
+ <list>
+ <item>The "echelon" information available through the
+ <url id="&url-debian-db;" name="developers' LDAP database">,
+ which indicates when's the last time a developer has posted to
+ a Debian mailing list. (This includes uploads via
+ debian-*-changes lists.) Also, remember to check whether the
+ maintainer is marked as "on vacation" in the database.
+
+ <item>The number of packages this maintainer is responsible for,
+ and the condition of those packages. In particular, are there
+ any RC bugs that have been open for ages? Furthermore, how
+ many bugs are there in general? Another important piece of
+ information is whether the packages have been NMUed, and if
+ so, by whom?
+
+ <item>Is there any activity of the maintainer outside of Debian?
+ For example, they might have posted something recently to
+ non-Debian mailing lists or news groups.
+ </list>
+ <p>
+One big problem are packages which were sponsored -- the maintainer is not
+an official Debian developer. The echelon information is not available for
+sponsored people, for example, so you need to find and contact the Debian
+developer who has actually uploaded the package. Given that they signed the
+package, they're responsible for the upload anyhow, and should know what
+happened to the person they sponsored.
+ <p>
+It is also allowed to post a query to &email-debian-devel;, asking if anyone
+is aware of the whereabouts of the missing maintainer.
+ <p>
+Once you have gathered all of this, you can contact &email-debian-qa;.
+People on this alias will use the information you provided in order to
+decide how to proceed. For example, they might orphan one or all of the
+packages of the maintainer. If a packages has been NMUed, they might prefer
+to contact the NMUer before orphaning the package -- perhaps the person who
+has done the NMU is interested in the package.
+ <p>
+One last word: please remember to be polite. We are all volunteers and
+cannot dedicate all of our time to Debian. Also, you are not aware of the
+circumstances of the person who is involved. Perhaps they might be
+seriously ill or might even had died -- you do not know who may be on the
+receiving side -- imagine how a relative will feel if they read the e-mail
+of the deceased and find a very impolite, angry and accusing message!)
+ <p>
+On the other hand, although we are volunteers, we do have a responsibility.
+So you can stress the importance of the greater good -- if a maintainer does
+not have the time or interest anymore, they should "let go" and give the
+package to someone with more time.
+
+
<sect id="newmaint">
<heading>Interacting with prospective Debian developers</heading>
<p>
complete list of available scripts.</p>
</sect1>
+ <sect1 id="autotools-dev">
+ <heading><package>autotools-dev</package></heading>
+ <p>
+Contains best practices for people maintaining packages that use
+<prgn>autoconf</prgn> and/or <prgn>automake</prgn>. Also contains
+canonical <file>config.sub</file> and <file>config.guess</file> files
+which are known to work on all Debian ports.</p>
+ </sect1>
+
+ <sect1 id="dpkg-repack">
+ <heading><package>dpkg-repack</package></heading>
+ <p>
+<prgn>dpkg-repack</prgn> creates Debian package file out of a package
+that has already been installed. If any changes have been made to the
+package while it was unpacked (e.g., files in <file>/etc</file> were
+modified), the new package will inherit the changes.</p>
+ <p>
+This utility can make it easy to copy packages from one computer to
+another, or to recreate packages that are installed on your system
+but no longer available elsewhere, or to store the current state of a
+package before you upgrade it.</p>
+ </sect1>
+
+ <sect1 id="alien">
+ <heading><package>alien</package></heading>
+ <p>
+<prgn>alien</prgn> converts binary packages between various packaging
+formats, including Debian, RPM (RedHat), LSB (Linux Standard Base),
+Solaris and Slackware packages.</p>
+ </sect1>
+
+ <sect1 id="debsums">
+ <heading><package>debsums</package></heading>
+ <p>
+<prgn>debsums</prgn> checks installed packages against their MD5 sums.
+Note that not all packages have MD5 sums, since they aren't required
+by Policy.</p>
+ </sect1>
+
<sect1 id="dpkg-dev-el">
<heading><package>dpkg-dev-el</package></heading>
<p>
<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
enhanced to support cross-compiling.
</sect1>
+
+
+ <sect id="tools-doc">
+ <heading>Documentation and information</heading>
+ <p>
+The following packages provide information for maintainers or help
+with building documentation.
+
+ <sect1 id="debiandoc-sgml">
+ <heading><package>debiandoc-sgml</package></heading>
+ <p>
+<package>debiandoc-sgml</package> provides the DebianDoc SGML DTD,
+which is commonly used for Debian documentation. This manual, for
+instance, is written in DebianDoc. It also provides scripts for
+building and styling the source to various output formats.</p>
+ <p>
+Documentation for the DTD can be found in the
+<package>debiandoc-sgml-doc</package> package.</p>
+ </sect1>
+
+ <sect1 id="debian-keyring">
+ <heading><package>debian-keyring</package></heading>
+ <p>
+Contains the public GPG and PGP keys of Debian developers. See <ref
+id="key-maint"> and the package documentation for more
+information.</p>
+ </sect1>
+
+ <sect1 id="debview">
+ <heading><package>debview</package></heading>
+ <p>
+<package>debview</package> provides an Emacs mode for viewing Debian
+binary packages. This lets you examine a package without unpacking
+it.</p>
+ </sect1>
</sect>
<!-- FIXME: add the following
- alien
- dpkg-repack
- debsums
- debiandoc-sgml, debiandoc-sgml-doc
- debian-keyring
questionable:
ucf
dpkg-awk
grep-dctrl
- debview
d-shlibs
wajig
magpie
apt-show-versions
pdbv
epm
+ apt-src
+ apt-build
rejected:
debaux: too new, unmaintained?
~ianmdlvl / developers-reference.git / blobdiff