<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.95 $">
+ <!entity cvs-rev "$Revision: 1.99 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
providing further information on a bug or even a patch, then do so!
<p>
Registration requires that you are familiar with Debian's philosophy
-and technical documentation. Furthermore, you need a GPG key which
-has been signed by an existing Debian maintainer. If your GPG key
+and technical documentation. Furthermore, you need a GnuPG key which
+has been signed by an existing Debian maintainer. If your GnuPG key
is not signed yet, you should try to meet a Debian maintainer in
person to get your key signed. There's a <url id="&url-gpg-coord;"
-name="GPG Key Signing Coordination page"> which should help you find
+name="GnuPG Key Signing Coordination page"> which should help you find
a maintainer close to you (If you cannot find a Debian maintainer
close to you, there's an alternative way to pass the ID check. You
-can send in a photo ID signed with your GPG key. Having your GPG
+can send in a photo ID signed with your GnuPG key. Having your GnuPG
key signed is the preferred way, however. See the
<url id="&url-newmaint-id;" name="identification page"> for more
information about these two options.)
have worked over the past months has to express his belief that you
can contribute to Debian successfully.
<p>
-When you have found an advocate, have your GPG key signed and have
+When you have found an advocate, have your GnuPG key signed and have
already contributed to Debian for a while, you're ready to apply.
You can simply register on our <url id="&url-newmaint-apply;"
name="application page">. After you have signed up, your advocate
<p>
The sections <em>main</em>, <em>contrib</em>, and <em>non-free</em>
are split into <em>subsections</em> to simplify the installation
-process and the maintenance of the archive. Subsections are not
-formally defined, except perhaps the `base' subsection.
-Subsections simply exist to simplify the organization and browsing of
-available packages. Please check the current Debian distribution to
-see which sections are available.
+process and the maintenance of the archive. Subsections simply exist to
+simplify the organization and browsing of available packages. The
+<url id="&url-debian-policy;" name="Debian Policy Manual"> gives
+the authoritative list of subsections.
+
<p>
Note however that with the introduction of package pools (see the top-level
<em>pool/</em> directory), the subsections in the form of subdirectories
to make sure everything in this distribution is working properly, it is
sometimes literally unstable.
<p>
-Packages get copied from <em>unstable</em> to <em>testing</em> if they
-satisfy certain criteria. To get into <em>testing</em> distribution, a
-package needs to be in the archive for two weeks and not have any
-release critical bugs. After that period, it will propagate into
-<em>testing</em> as soon as anything it depends on is also added. This
-process is automatic. You can see some notes on this system as well
-as <tt>update_excuses</tt> (describing which packages are valid
-candidates, which are not, and why not) at <url
-id="&url-testing-maint;">.
+The testing distribution is generated automatically by taking
+packages from unstable if they satisfy certain criteria. Those
+criteria should ensure a good quality for packages within testing.
+The <ref id="testing-scripts"> are launched each day after the
+new packages have been installed.
<p>
After a period of development, once the release manager deems fit, the
<em>testing</em> distribution is frozen, meaning that the policies
symbolic links for <em>stable</em>, <em>testing</em>, and
<em>unstable</em> point to the appropriate release directories.
+ <sect id="testing-scripts">
+ <heading>The testing scripts</heading>
+ <p>
+The testing scripts are run each day after the installation of the
+updated packages. They generate the <file>Packages</file> files for
+the <em>testing</em> distribution, but they do so in an intelligent manner
+trying to avoid any inconsistency and trying to use only
+non-buggy packages.
+ <p>The inclusion of a package from <em>unstable</em> is conditionned:
+<list>
+ <item>
+The package must have been available in <em>unstable</em> for several days;
+the precise number depends on the urgency field's value of the upload. It
+is 10 days for low urgency, 5 days for medium urgency and 2 days for high
+urgency. Those delays may be doubled during a freeze.
+ <item>
+It must have less release-critical bugs than the version available
+in <em>testing</em>;
+ <item>
+It must be available on all architectures on which it has been
+previously built;
+ <item>
+It must not break any dependency of a package that is already available
+in <em>testing</em>;
+ <item>
+The packages on which it depends must either be available in <em>testing</em>
+or they must be accepted into <em>testing</em> at the same time (and they will
+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 part of the
+<package>devscripts</package> package. It can be easily put in a crontab
+to keep someone informed of the progression of his packages in testing.
+ <p>
+The <tt>update_excuses</tt> file does not always give the precise reason
+why the package is refused, one may have to find it by himself by looking
+what would break with the inclusion of the package. The <url
+id="&url-testing-faq;" name="testing FAQ"> gives some more information
+about the usual problems which may be causing such troubles.
+ <p>
+Sometimes, some packages never enter testing 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.
+
<chapt id="pkgs">Managing Packages
<p>
<tt>ftp-master</tt>'s <tt>Incoming</tt>, i.e., a <tt>.changes</tt> files
along with the other files mentioned in the <tt>.changes</tt>. The
queue daemon also checks that the <tt>.changes</tt> is correctly
-PGP-signed by a Debian developer, so that no bogus files can find
+signed with GnuPG or OpenPGP by a Debian developer, so that no bogus files can find
their way to <tt>ftp-master</tt> via this queue. Please also make sure that
the <tt>Maintainer</tt> field in the <tt>.changes</tt> contains
<em>your</em> e-mail address. The address found there is used for all
the ``debian-changes'' lists. This is now done automatically by the archive
maintenance software when it runs (usually once a day). You just need to use
a recent <package>dpkg-dev</package> (>= 1.4.1.2). The mail generated by
-the archive maintenance software will contain the PGP/GPG signed
+the archive maintenance software will contain the OpenPGP/GnuPG signed
<tt>.changes</tt> files that you uploaded with your package.
Previously, <prgn>dupload</prgn> used to send those announcements, so
please make sure that you configured your <prgn>dupload</prgn> not to
package is released with <tt>Distribution:</tt> set to `unstable',
or `experimental', the announcement will be
posted to &email-debian-devel-changes; instead.
- <p>
-The <prgn>dupload</prgn> program is clever enough to determine
-where the announcement should go, and will automatically mail the
-announcement to the right list. See <ref id="dupload">.
<sect1 id="upload-notification">
<heading>Notification that a new package has been installed</heading>
<sect id="bug-handling">Handling package bugs
+ <p>
+Often as a package maintainer, you find bugs in other packages or else
+have bugs reported to your packages which need to be reassigned. The
+<url id="&url-bts-control;" name="BTS instructions"> can tell you how
+to do this. Some information on filing bugs can be found in <ref
+id="submit-bug">.
<sect1>Monitoring bugs
<p>
# ask for weekly reports of bugs in my packages
&cron-bug-report;
</example>
-Replace <var>address</var> with you official Debian
+Replace <var>address</var> with your official Debian
maintainer address.
- <sect id="submit-bug">Submitting bugs
- <p>
-Often as a package maintainer, you find bugs in other packages or else
-have bugs reported to your packages which need to be reassigned. The
-<url id="&url-bts-control;" name="BTS instructions"> can tell you how
-to do this.
- <p>
-We encourage you to file bugs when there are problems. 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).
-
<sect1 id="bug-answering">Responding to bugs
<p>
Make sure that any discussions you have about bugs are sent both to
the original submitter of the bug, and the bug itself (e.g.,
<email>123@bugs.debian.org</email>).
<p>
-You should <em>never</em> close bugs via the bug server `close'
+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 feedback on why the bug was closed.
+submitter will not receive any information about why the bug was
+closed.
<sect1 id="bug-housekeeping">Bug housekeeping
<p>
/closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
</example>
-The author prefers the <tt>(closes: Bug#<var>XXX</var>)</tt> syntax,
-since it stands out from the rest of the changelog entries.
+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 <tt>.changes</tt> file to
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.
+
+
+
<chapt id="beyond-pkging">
<heading>Beyond Packaging</heading>
<p>
<sect id="submit-bug">
<heading>Bug Reporting</heading>
<p>
-We encourage you to file bugs as you find them in Debian packages.
+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.
+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.