+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:
+<example>
+acme-cannon (3.1415) unstable; urgency=low
+
+ * Frobbed with options (closes: Bug#98339)
+ * Added safety to prevent operator dismemberment, closes: bug#98765,
+ bug#98713, #98714.
+ * Added man page. Closes: #98725.
+</example>
+
+Technically speaking, the following Perl regular expression is what is
+used:
+<example>
+ /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
+</example>
+
+The author prefers the <tt>closes: #<var>XXX</var></tt> syntax, as
+one of the most concise and easiest to integrate with the text of the
+<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
+<email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your
+bug number.
+
+
+ <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.
+ <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="misc-advice">
+ <heading>Miscellaenous 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 he installs 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
+website 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>
+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>
+
+
+
+ <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 choosing what is
+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;/<your-email>@your-isp.com</tt>.
+
+ <sect1 id="submit-many-bugs">Reporting lots of bugs at once
+ <p>
+Reporting a great number of bugs for the same problem on a great
+number of different packages &mdash i.e., more than 10 &mdash is a deprecated
+practice. Take all possible steps to avoid submitting bulk bugs at
+all. For instance, if checking for the problem can be automated, add
+a new check to <package>lintian</package> so that an error or warning
+is emitted.
+ <p>
+If you report more than 10 bugs on the same topic at once, it is
+recommended that you send a message to &email-debian-devel; describing
+your intention before submitting the report. This will allow other
+developers to verify that the bug is a real problem. In addition, it
+will help prevent a situation in which several maintainers start
+filing the same bug report simultaneously.
+ <p>
+Note that when sending lots of bugs on the same subject, you should
+send the bug report to <email>maintonly@bugs.debian.org</email> so
+that the bug report is not forwarded to the bug distribution mailing
+list.
+
+
+ <sect id="qa-effort">Quality Assurance effort
+ <p>
+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. 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
+in order to catch up the backlog of bugs that you have (you can ask
+for help on &email-debian-qa; or &email-debian-devel;).
+
+ <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 he was last seen. Collect any important package names
+he maintains and any Release Critical bugs filled 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>
+During your lifetime within Debian, you will have to contact other
+maintainers for various reasons. You may want to discuss a new
+way of cooperating between a set of related packages, or you may
+simply remind someone that a new upstream version is available
+and that you need it.
+ <p>
+Looking up the email address of the maintainer for the package can be
+distracting. Fortunately, there is a simple email alias,
+<tt><package>@&packages-host;</tt>, which provides a way to
+email the maintainer, whatever their individual email address (or
+addresses) may be. Replace <tt><package></tt> with the name of
+a source or a binary package.
+ <p>
+You may also be interested by contacting the persons who are
+subscribed to a given source package via <ref id="pkg-tracking-system">.
+You can do so by using the <tt><package-name>@&pts-host;</tt>
+email address.
+
+
+ <sect id="newmaint">
+ <heading>Interacting with prospective Debian developers</heading>
+ <p>
+Debian's success depends on its ability to attract and retain new and
+talented volunteers. If you are an experienced developer, we
+recommend that you get involved with the process of bringing in new
+developers. This section describes how to help new prospective
+developers.
+
+
+ <sect1 id="sponsoring">Sponsoring packages
+ <p>
+Sponsoring a package means uploading a package for a maintainer who is not
+able to do it on their own, a new maintainer applicant. Sponsoring a package
+also means accepting responsibility for it.
+ <p>
+If you wish to volunteer as a sponsor, you can sign up at <url
+id="&url-sponsors;">.
+ <p>
+New maintainers usually have certain difficulties creating Debian packages
+— this is quite understandable. That is why the sponsor is there, to check
+the package and verify that it is good enough for inclusion in Debian.
+(Note that if the sponsored package is new, the FTP admins will also have to
+inspect it before letting it in.)
+ <p>
+Sponsoring merely by signing the upload or just recompiling is
+<strong>definitely not recommended</strong>. You need to build the source
+package just like you would build a package of your own. Remember that it
+doesn't matter that you left the prospective developer's name both in the
+changelog and the control file, the upload can still be traced to you.
+ <p>
+If you are an application manager for a prospective developer, you can also
+be their sponsor. That way you can also verify how the applicant is
+handling the 'Tasks and Skills' part of their application.
+
+ <sect1>Managing sponsored packages
+ <p>
+By uploading a sponsored package to Debian, you are certifying that
+the package meets minimum Debian standards. That implies that you
+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
+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 he hasn't
+altered the upstream files in the <file>.orig.tar.gz</file> file that he's
+providing.
+ <p>
+Do not be afraid to write the sponsoree back and point out changes
+that need to be made. It often takes several rounds of back-and-forth
+email before the package is in acceptable shape. Being a sponsor
+means being a mentor.
+ <p>
+Once the package meets Debian standards, build the package with
+<example>dpkg-buildpackage -us -uc</example> and sign it
+with <example>debsign -m <your-email-addr> <changes-file></example>
+before uploading it to the incoming directory.
+ <p>
+The Maintainer field of the <file>control</file> file and the
+<file>changelog</file> should list the person who did the packaging, i.e. the
+sponsoree. The sponsoree will therefore get all the BTS mail about the
+package.
+ <p>
+If you prefer to leave a more evident trace of your sponsorship job, you
+can add a line stating it in the most recent changelog entry.
+ <p>
+You are encouraged to keep tabs on the package you sponsor using
+<ref id="pkg-tracking-system">.
+
+ <sect1>Advocating new developers
+ <p>
+See the page about <url id="&url-newmaint-advocate;"
+name="advocating a prospective developer"> at the Debian web site.
+
+ <sect1>Handling new maintainer applications
+ <p>
+Please see <url id="&url-newmaint-amchecklist;" name="Checklist for
+Application Managers"> at the Debian web site.
+
+
+
+ <appendix id="tools">Overview of Debian Maintainer Tools
+ <p>
+This section contains a rough overview of the tools available to
+maintainers. The following is by no means complete or definitive, but
+just a guide to some of the more popular tools.
+ <p>
+Debian maintainer tools are meant to help convenience developers and
+free their time for critical tasks. As Larry Wall says, there's more
+than one way to do it.
+ <p>
+Some people prefer to use high-level package maintenance tools and
+some do not. Debian is officially agnostic on this issue; any tool
+which gets the job done is fine. Therefore, this section is not meant
+to stipulate to anyone which tools they should use or how they should
+go about with their duties of maintainership. Nor is it meant to
+endorse any particular tool to the exclusion of a competing tool.
+ <p>
+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>.
+
+
+ <sect id="dpkg-dev">
+ <heading><package>dpkg-dev</package>
+ <p>
+<package>dpkg-dev</package> contains the tools (including
+<prgn>dpkg-source</prgn>) required to unpack, build and upload Debian
+source packages. These utilities contain the fundamental, low-level
+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">
+ <heading><package>debconf</package></heading>
+ <p>
+<package>debconf</package> provides a consistent interface to
+configuring packages interactively. It is user interface
+independent, allowing end-users to configure packages with a
+text-only interface, an HTML interface, or a dialog interface. New
+interfaces can be added modularly.
+ <p>
+You can find documentation for this package in the
+<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.
+ <p>
+
+
+ <sect id="debhelper">
+ <heading><package>debhelper</package>
+ <p>
+<package>debhelper</package> is a collection of programs that can be
+used in <file>debian/rules</file> to automate common tasks related to
+building binary Debian packages. Programs are included to install
+various files into your package, compress files, fix file permissions,
+integrate your package with the Debian menu system.
+ <p>
+Unlike some approaches, <package>debhelper</package> is broken into
+several small, granular commands which act in a consistent manner. As
+such, it allows a greater granularity of control than some of the
+other "debian/rules tools".
+ <p>
+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>.
+
+
+ <sect id="debmake">
+ <heading><package>debmake</package>
+ <p>
+<package>debmake</package>, a pre-cursor to
+<package>debhelper</package>, is a less granular
+<file>debian/rules</file> assistant. It includes two main programs:
+<prgn>deb-make</prgn>, which can be used to help a maintainer convert
+a regular (non-Debian) source archive into a Debian source package;
+and <prgn>debstd</prgn>, which incorporates in one big shot the same
+sort of automated functions that one finds in
+<package>debhelper</package>.
+ <p>
+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>.
+
+
+ <sect 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
+<file>debian/rules</file> and other necessary files in the
+<file>debian/</file> subdirectory.
+ <p>
+Note that <package>yada</package> is called "essentially unmaintained"
+by it's own maintainer, Charles Briscoe-Smith. As such, it can be
+considered deprecated.
+
+
+ <sect 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.
+
+
+ <sect 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
+package from the CVS repository, and helps in integrating upstream
+changes into the repository.
+ <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
+<em>experimental</em> distributions, along with the other benefits of
+a version control system.