<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.135 $">
+ <!entity cvs-rev "$Revision: 1.149 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<copyright>
<copyrightsummary>
-copyright ©1998—2002 Adam Di Carlo</copyrightsummary>
+copyright © 1998—2002 Adam Di Carlo</copyrightsummary>
<copyrightsummary>
-copyright ©2002 Raphaël Hertzog</copyrightsummary>
+copyright © 2002 Raphaël Hertzog</copyrightsummary>
<copyrightsummary>
-copyright ©1997, 1998 Christian Schwarz</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
<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
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
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.
(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
</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
<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
<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">
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
<file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
- testing this is <tt>testing-security</tt>. Do not target
+ 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
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 <file>*.orig.tar.gz</file> as used in the
normal archive, otherwise it is not possible to move the security
exactly meet the team's requirements, it will cause many problems and
delays in dealing with the unwanted upload.
<p>
+<em>DO NOT</em> upload your fix to proposed-updates without
+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
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
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
-excellent <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.
+
+
<!--
<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).
+ <sect id="bpp-config-mgmt">
+ <heading>Configuration management with <package>debconf</package></heading>
+
<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>.
+<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>
-Additionally, dbs provides facilities to create the patches and to keep
-track of what they are for.
+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="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).
- <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.
- <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 -->
- <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
<sect1 id="bpp-autotools">
<heading>Packages using
<prgn>autoconf</prgn>/<prgn>automake</prgn></heading>
- <p>
-Some very good packaging practices for packages 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.
+ <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
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">
- <heading>Proper use of <package>debconf</package></heading>
- <p>
-<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>
-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.
+ </sect1>
+ </sect>
<!--
<sect1 id="custom-config-files">Custom configuration files
<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.
+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 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
+For example, apart from the usual description that you might 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.
+For consistency and aesthetics, you should capitalize the first letter
+of the description. Don't put a full stop (period) at the end.
<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>.
+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;.
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;
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
<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">.
+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").
<sect id="debconf">
<package>debmake</package>.
+ <sect 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.
+
+
<sect id="yada">
<heading><package>yada</package>
<p>
finalizing a version and listing the package's current bugs.
- <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).
-
<!-- FIXME: add the following
- dpkg-awk
alien
dpkg-repack
+ debsums
+ debiandoc-sgml, debiandoc-sgml-doc
+ debian-keyring
+
+questionable:
+ ucf
+ dpkg-awk
grep-dctrl
+ debview
-->
~ianmdlvl / developers-reference.git / blobdiff