<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.94 $">
+ <!entity cvs-rev "$Revision: 1.99 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
So, you've read all the documentation, you've gone through the <url
id="&url-newmaint-guide;" name="Debian New Maintainers' Guide">,
understand what everything in the <package>hello</package> example
-package is for, and you're about to Debianize your favourite piece of
+package is for, and you're about to Debianize your favorite piece of
software. How do you actually become a Debian developer so that your
work can be incorporated into the Project?
<p>
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
but are waiting for your new maintainer application to go through, you
might be able find a sponsor to upload your package for you. Sponsors
are people who are official Debian maintainers, and who are willing to
-criticize and upload your packages for you. Sponsorees can request a
-sponsors at <url id="&url-sponsors;">.
+criticize and upload your packages for you. Those who are seeking a
+sponsor can request one at <url id="&url-sponsors;">.
<p>
If you wish to be a mentor and/or sponsor, more information is
available in <ref id="newmaint">.
id="&url-pgp-faq;" name="PGP FAQ">.
<p>
If you add signatures to your public key, or add user identities, you
-can update the debian keyring by sending your key to the key server at
+can update the debian key ring by sending your key to the key server at
<tt>&keyserver-host;</tt>. If you need to add a completely new key,
or remove an old key, send mail to &email-debian-keyring;. The same
key extraction routines discussed in <ref id="registering"> apply.
The other developers need to know that you're on vacation so that they'll
do whatever is needed when such a problem occurs. Usually this means that
other developers are allowed to NMU (see <ref id="nmu">) your package if a
-big problem (release critical bugs, security update, ...) occurs while
+big problem (release critical bugs, security update, etc.) occurs while
you're on vacation.
<p>
In order to inform the other developers, there's two things that you should do.
forward these patches upstream.
<p>
If you need to modify the upstream sources in order to build a policy
-conformant package, then you should propose a nice fix to the upstream
+compliant package, then you should propose a nice fix to the upstream
developers which can be included there, so that you won't have to
modify the sources of the next upstream version. Whatever changes you
need, always try not to fork from the upstream sources.
<sect1 id="devel-db">The Developers Database
<p>
-The Deverlopers Database, at <url id="&url-debian-db;">, is an LDAP
+The Developers Database, at <url id="&url-debian-db;">, is an LDAP
directory for managing Debian developer attributes. You can use this
resource to search the list of Debian developers. For information on
keeping your entry the developer database up-to-date, see <ref
<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 maintainance 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>
By default, <prgn>dpkg-genchanges</prgn> and
<prgn>dpkg-buildpackage</prgn> will include the original source tar
file if and only if the Debian revision part of the source version
-number is 0 or 1, indicating a new upstream version. This behaviour
+number is 0 or 1, indicating a new upstream version. This behavior
may be modified by using <tt>-sa</tt> to always include it or
<tt>-sd</tt> to always leave it out.
<p>
package should only be uploaded to stable if one of the following happens:
<list>
<item>a security problem (e.g. a Debian security advisory)
- <item>a truely critical functionality problem
+ <item>a truly critical functionality problem
<item>the package becomes uninstallable
<item>a released architecture lacks the package
</list>
It is discouraged to change anything else in the package that isn't
important, because even trivial fixes can cause bugs later on. Uploading
new upstream versions to fix security problems is deprecated; applying the
-specific patch from the new upstream version to the old one ("backporting"
+specific patch from the new upstream version to the old one ("back-porting"
the patch) is the right thing to do in most cases.
<p>
Packages uploaded to <em>stable</em> need to be compiled on systems running
<ftppath>/pub/UploadQueue/</ftppath>. Please note that you should transfer
the changes file last. Otherwise, your upload may be rejected because the
archive maintenance software will parse the changes file and see that not
-all files have been uploaded. If you don't want to bother with transfering
+all files have been uploaded. If you don't want to bother with transferring
the changes file last, you can simply copy your files to a temporary
directory on <tt>ftp-master</tt> and then move them to
<tt>&us-upload-dir;</tt>.
to <tt>ftp-master</tt>. Instead, upload the package to
<ftpsite>non-us.debian.org</ftpsite>, placing the files in
<tt>&non-us-upload-dir;</tt> (both <ref id="dupload"> and <ref
-id="dput"> can be used also, with the right invokation). By default,
+id="dput"> can be used also, with the right invocation). By default,
you can use the same account/password that works on
<tt>ftp-master</tt>. If you use anonymous FTP to upload, place the
files into <ftppath>/pub/UploadQueue/</ftppath>.
<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>
called a non-maintainer upload, or NMU.
<p>
Debian porters, who compile packages for different architectures,
-occasionnaly do binary-only NMUs as part of their porting activity
+occasionally do binary-only NMUs as part of their porting activity
(see <ref id="porting">). Another reason why NMUs are done is when a
Debian developers needs to fix another developers' packages in order to
address serious security problems or crippling bugs, especially during
The way to invoke <prgn>dpkg-buildpackage</prgn> is as
<tt>dpkg-buildpackage -B -m<var>porter-email</var></tt>. Of course,
set <var>porter-email</var> to your email address. This will do a
-binary-only build of only the architecture-dependant portions of the
+binary-only build of only the architecture-dependent portions of the
package, using the `binary-arch' target in <file>debian/rules</file>.
<sect2 id="binary-only-nmu">
If, on the other hand, you need to change the <em>subsection</em> of
one of your packages (e.g., ``devel'', ``admin''), the procedure is
slightly different. Correct the subsection as found in the control
-file of the package, and reupload that. Also, you'll need to get the
+file of the package, and re-upload that. Also, you'll need to get the
override file updated, as described in <ref id="override-file">.
<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>
* Frobbed with options (closes: Bug#98339)
* Added safety to prevent operator dismemberment, closes: bug#98765,
bug#98713, #98714.
- * Added manpage. Closes: #98725.
+ * Added man page. Closes: #98725.
</example>
Technically speaking, the following Perl regular expression is what is
/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.
<p>
<package>debconf</package> provides a consistent interface to
configuring packages interactively. It is user interface
-independant, allowing end-users to configure packages with a
+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>
<sect id="dupload">
<heading><package>dupload</package>
<p>
-<package>dupload</package> is a package and a script to automagically
+<package>dupload</package> is a package and a script to automatically
upload Debian packages to the Debian archive, to log the upload, and
to send mail about the upload of a package. You can configure it for
new upload locations or methods.
<heading><package>debootstrap</package>
<p>
The <package>debootstrap</package> package and script allows you to
-"bootstrap" a Debian base system into any part of your filesystem.
+"bootstrap" a Debian base system into any part of your file-system.
By "base system", we mean the bare minimum of packages required to
operate and install the rest of the system.
<p>
~ianmdlvl / developers-reference.git / blobdiff