+ <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.
+ <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>
+
+ <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;">.
+
+<!--
+ <sect1 id="pkg-mgmt-cvs">Managing a package with CVS
+ <p>
+ &FIXME; presentation of cvs-buildpackage, updating sources
+ 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).
+ <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="specific-practices">
+ <heading>Specific packaging practices</heading>
+
+<!--
+ <sect1 id="bpp-kernel">Kernel modules/patches
+ <p>
+ &FIXME; Heavy use of kernel-package. provide files in
+ /etc/modutils/ for module configuration.
+-->
+
+ <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.
+
+
+ <sect1 id="bpp-libraries">Libraries
+ <p>
+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
+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
+ <p>
+Several subsets 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
+<package>libmldbm-perl</package> (arch independent perl module).
+ <item>
+Python related packages have their python policy:
+&file-python-policy; (in the python package).
+ <item>
+Emacs related packages have the <url id="&url-emacs-policy;"
+name="emacs policy">.
+ <item>
+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.
+</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 id="custom-config-files">Custom configuration files
+ <p>
+ &FIXME; speak of "ucf", explain solution with a template,
+ explain conf.d directories
+
+ <sect1 id="config-with-db">Use of an external database
+ <p>
+ &FIXME; The software may require a database that you need to setup.
+ But the database may be local or distant. Thus you can't depend
+ on a database server but just on the corresponding library.
+
+ 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;.
+
+
+
+ <chapt id="beyond-pkging">
+ <heading>Beyond Packaging</heading>
+ <p>
+Debian is about a lot more than just packaging software and
+maintaining those packages. This chapter contains information about
+ways, often really critical ways, to contribute to Debian beyond
+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 in choosing
+the most critical thing to spend their time on.
+
+ <sect id="submit-bug">
+ <heading>Bug Reporting</heading>
+ <p>
+We encourage you to file bugs as you find them in Debian packages. In
+fact, Debian developers are often the first line testers. Finding and
+reporting bugs in other developer's packages improves the quality of
+Debian.
+ <p>
+Try to submit the bug from a normal user account at which you are
+likely to receive mail. Do not submit bugs as root.
+ <p>
+Make sure the bug is not already filed against a package. Try to do a
+good job reporting a bug and redirecting it to the proper location.
+For extra credit, you can go through other packages, merging bugs
+which are reported more than once, or setting bug severities to
+`fixed' when they have already been fixed. Note that when you are
+neither the bug submitter nor the package maintainer, you should
+not actually close the bug (unless you secure permission from the
+maintainer).
+ <p>
+From time to time you may want to check what has been going on
+with the bug reports that you submitted. Take this opportunity to
+close those that you can't reproduce anymore. To find
+out all the bugs you submitted, you just have to visit
+<tt>http://&bugs-host;/from:<your-email-addr></tt>.
+
+ <sect1 id="submit-many-bugs">Reporting lots of bugs at once