<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.96 $">
+ <!entity cvs-rev "$Revision: 1.102 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
to &email-debian-devel-req;. In case of problems, contact the list
administrator at &email-listmaster;. More information on available
mailing lists can be found in <ref id="mailing-lists">.
+&email-debian-devel-announce; is another list which is mandatory
+for anyone who wish to follow Debian's development.
<p>
You should subscribe and lurk (that is, read without posting) for a
bit before doing any coding, and you should post about your intentions
Debian uses the <prgn>GNU Privacy Guard</prgn> (package
<package>gnupg</package> version 1 or better) as its baseline standard.
You can use some other implementation of OpenPGP as well. Note that
-OpenPGP is a open standard based on <url id="&url-rfc2440;" name="RFC
+OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC
2440">.
<p>
The recommended public key algorithm for use in Debian development
Some countries restrict the use of cryptographic software by their
citizens. This need not impede one's activities as a Debian package
maintainer however, as it may be perfectly legal to use cryptographic
-products for authentication, rather than encryption purposes (as is
-the case in France). &debian-formal; does not require the use of
-cryptography <em>qua</em> cryptography in any manner. If you live in a
-country where use of cryptography even for authentication is forbidden
+products for authentication, rather than encryption purposes.
+&debian-formal; does not require the use of cryptography <em>qua</em>
+cryptography in any manner. If you live in a country where use of
+cryptography even for authentication is forbidden
then please contact us so we can make special arrangements.
<p>
To apply as a new maintainer, you need an existing Debian maintainer
Maintainer's Corner"> at the Debian web site. Make sure that you
are familiar with the necessary steps of the New Maintainer process
before actually applying. If you are well prepared, you can save
-a lot of timer later on.
+a lot of time later on.
<sect id="mentors">Debian mentors and sponsors
key extraction routines discussed in <ref id="registering"> apply.
<p>
You can find a more in-depth discussion of Debian key maintenance in
-the documentation
for the <package>debian-keyring</package> package.
+the documentation
of the <package>debian-keyring</package> package.
<sect id="voting">Voting
<chapt id="resources">Resources for Debian Developers
<p>
In this chapter you will find a very brief road map of the Debian
-mailing lists, the main Debian servers, and other Debian machines
-which may be available to you as a developer.
+mailing lists, the main Debian servers, other Debian machines
+which may be available to you as a developer, and all the other
+resources that are available to help you in your maintainer work.
<sect id="mailing-lists">Mailing lists
<p>
&email-debian-private; unless it is really necessary. Moreover, do
<em>not</em> forward email from that list to anyone. Archives of this
list are not available on the web for obvious reasons, but you can see
-them using your shell account <tt>master.debian.org</tt> and looking
+them using your shell account on <tt>master.debian.org</tt> and looking
in the <file>~debian/archive/debian-private</file> directory.
<p>
&email-debian-email; is a special mailing list used as a grab-bag
<sect1 id="servers-ftp-master">The ftp-master server
<p>
-The ftp-master server, <tt>ftp-master.debian.org</tt> (or
+The ftp-master server, <tt>&ftp-master-host;</tt> (or
<tt>auric.debian.org</tt>), holds the canonical copy of the Debian
archive (excluding the non-US packages). Generally, package uploads
go to this server; see <ref id="upload">.
<sect1 id="servers-www">The WWW server
<p>
-The main web server, <tt>www.debian.org</tt>, is also known as
+The main web server, <tt>&www-host;</tt>, is also known as
<tt>klecker.debian.org</tt>. All developers are given accounts on this
machine.
<p>
<p>
To request a CVS area, send a request via email to
&email-debian-admin;. Include the name of the requested CVS area,
-Debian account should own the CVS root area, and why you need it.
+the Debian account that should own the CVS root area, and why you need it.
<sect1 id="devel-db">The Developers Database
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
-id="user-maint">.
+id="user-maint">. Part of this information is also available through
+the finger service on Debian servers, try
+<prgn>finger yourlogin@debian.org</prgn> to see what it reports.
<sect id="servers-mirrors">Mirrors of Debian servers
<tt>dists/stable</tt> contains three directories, namely <em>main</em>,
<em>contrib</em>, and <em>non-free</em>.
<p>
-In each of the areas, there is a directory with the source packages
-(<tt>source</tt>), a directory for each supported architecture
-(<tt>binary-i386</tt>, <tt>binary-m68k</tt>, etc.), and a directory
-for architecture independent packages (<tt>binary-all</tt>).
+In each of the areas, there is a directory for the source packages
+(<tt>source</tt>) and a directory for each supported architecture
+(<tt>binary-i386</tt>, <tt>binary-m68k</tt>, etc.).
<p>
The <em>main</em> area contains additional directories which holds
the disk images and some essential pieces of documentation required
for installing the Debian distribution on a specific architecture
(<tt>disks-i386</tt>, <tt>disks-m68k</tt>, etc.).
- <p>
-The <em>binary-*</em> and <em>source</em> directories are divided
-further into <em>subsections</em>.
<sect1>Sections
but may fail other requirements. For instance, they may depend on
non-free packages.
<p>
-Packages which do not apply to the DFSG are placed in the
+Packages which do not conform to the DFSG are placed in the
<em>non-free</em> section. These packages are not considered as part
of the Debian distribution, though we support their use, and we
provide infrastructure (such as our bug-tracking system and mailing
also have ports underway to non-Linux kernel. Aside from
<em>i386</em> (our name for Intel x86), there is <em>m68k</em>,
<em>alpha</em>, <em>powerpc</em>, <em>sparc</em>, <em>hurd-i386</em>,
-and <em>arm</em>, as of this writing.
+<em>arm</em>, <em>ia64</em>, <em>hppa</em>, <em>s390</em>, <em>mips</em>,
+<em>mipsel</em> and <em>sh</em> as of this writing.
<p>
&debian-formal; 1.3 is only available as <em>i386</em>. Debian 2.0
shipped for <em>i386</em> and <em>m68k</em> architectures. Debian 2.1
ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and
-<em>sparc</em> architectures. Debian 2.2 adds support for the
-<em>powerpc</em> and <em>arm</em> architectures.
+<em>sparc</em> architectures. Debian 2.2 added support for the
+<em>powerpc</em> and <em>arm</em> architectures. Debian 3.0 adds
+support of five new architectures : <em>ia64</em>, <em>hppa</em>,
+<em>s390</em>, <em>mips</em> and <em>mipsel</em>.
<p>
Information for developers or uses about the specific ports are
available at the <url id="&url-debian-ports;" name="Debian Ports web
pages">.
- <sect1>Subsections
+<!-- <sect1>Subsections
<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
will eventually cease to exist. They will be kept in the packages' `Section'
-header fields, though.
+header fields, though. -->
<sect1>Packages
<p>
(that's why this distribution is sometimes called the <em>development
distribution</em>). Every Debian developer can update his or her
packages in this distribution at any time. Thus, the contents of this
-distribution change from day-to-day. Since no special effort is done
+distribution changes from day-to-day. Since no special effort is done
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.
+<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
<tt>proposed-updates</tt> directory. Those packages in
<tt>proposed-updates</tt> that pass muster are periodically moved as a
batch into the stable distribution and the revision level of the
-stable distribution is incremented (e.g., ‘3.0’ becomes ‘3.0r1’,
-‘2.2r4’ becomes ‘2.0r5’, and so forth).
+stable distribution is incremented (e.g., ‘3.0’ becomes
+‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and
+so forth).
<p>
Note that development under <em>unstable</em> continues during the
freeze period, since the <em>unstable</em> distribution remains in
<sect2>Experimental
<p>
-The <em>experimental</em> distribution is a specialty distribution.
+The <em>experimental</em> distribution is a special distribution.
It is not a full distribution in the same sense as `stable' and
`unstable' are. Instead, it is meant to be a temporary staging area
for highly experimental software where there's a good chance that the
Some experimental software can still go into <em>unstable</em>, with a few
warnings in the description, but that isn't recommended because packages
from <em>unstable</em> are expected to propagate to <em>testing</em> and
-thus to <em>stable</em>.
+thus to <em>stable</em>. You should not be afraid to use
+<em>experimental</em> since it does not cause any pain to the ftpmasters,
+the experimental packages are automatically removed once you upload
+the package in <em>unstable</em> with a higher version number.
<p>
New software which isn't likely to damage your system can go directly into
<em>unstable</em>.
symbolic links for <em>stable</em>, <em>testing</em>, and
<em>unstable</em> point to the appropriate release directories.
+ <sect id="incoming-system">
+ <heading>The Incoming system
+ <p>
+The Incoming system is responsible of collecting updated packages and
+installing them in the Debian archive. It consists of a set of
+directories and scripts that are installed both on <tt>&ftp-master-host;</tt>
+and <tt>&non-us-host;</tt>.
+ <p>
+Packages are uploaded by all the maintainers into an <tt>unchecked</tt>
+directory. This directory is scanned every 15 minutes by the katie script
+that verifies the integrity of the package and the cryptographic
+signature. If the package is considered ready to be installed, it
+is moved into an <tt>accepted</tt> directory. If it is the first upload of
+the package then it is moved in a <tt>new</tt> directory waiting an
+approval of the ftpmasters. If the package contains files to be installed
+"by-hand" is is moved in the <tt>byhand</tt> directory waiting a manual
+installation by the ftpmasters. Otherwise, if any error has been detected,
+the package is refused and is moved in the <tt>reject</tt> directory.
+ <p>
+Once the package is accepted the system sends a confirmation
+mail to the maintainer, closes all the bugs marked as fixed by the upload
+and the autobuilders may start recompiling it. The package is now publically
+accessible at <url id="&url-incoming;"> (there is no
+such URL for packages in the non-US archive) until it is really installed
+in the Debian archive. This happens only once a day, the package
+is then removed from incoming and installed in the pool along with all
+the other packages. Once all the other updates (generating new
+<tt>Packages</tt> and <tt>Sources</tt> index files for example) have been
+made, a special script is called to ask all the primary mirrors to update
+themselves.
+ <p>
+All debian developers have write access to the <tt>unchecked</tt>
+directory in order to upload their packages, they also have that access
+to the <tt>reject</tt> directory in order to remove their bad uploads
+or to move some files back in the <tt>unchecked</tt> directory. But
+all the other directories are only writable by the ftpmasters, that is
+why you can not remove an upload once it has been accepted.
+
+ <sect1 id="delayed-incoming">Delayed incoming
+ <p>
+The <tt>unchecked</tt> directory has a special <tt>DELAYED</tt>
+subdirectory. It is itself subdivised in nine directories
+called <tt>1-day</tt> to <tt>9-day</tt>. Packages which are uploaded in
+one of those directories will be moved in the real unchecked
+directory after the corresponding number of days.
+This is done by a script that is run each day and which moves the
+packages between the directories. Those which are in "1-day" are
+installed in <tt>unchecked</tt> while the others are moved in the
+adjacent directory (for example, a package in <tt>5-day</tt> will
+be moved in <tt>4-day</tt>). This feature is particularly useful
+for people who are doing non-maintainer uploads. Instead of
+waiting before uploading a NMU, it is uploaded as soon as it is
+ready but in one of those <tt>DELAYED/x-day</tt> directories.
+That leaves the corresponding number of days to the maintainer
+in order to react and upload himself another fix if he is not
+completely satisfied with the NMU. Alternatively he can remove
+the NMU by himself.
+ <p>
+The use of that delayed feature can be simplified with a bit
+of integration with your upload tool, the following addition to
+the <prgn>dupload</prgn> configuration file should be
+considered.
+ <p>
+<example>
+$delay = ($ENV{DELAY} || 7);
+$cfg{'delayed'} = {
+ fqdn => "ftp-master.debian.org",
+ login => "yourdebianlogin",
+ incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
+ visibleuser => "yourdebianlogin",
+ visiblename => "debian.org",
+ fullname => "Your Full Name",
+ dinstall_runs => 1,
+ method => "scpb"
+};
+</example>
+ <p>
+<prgn>dupload</prgn> can now be used to easily upload a package
+in one of the delayed directories :
+<example>DELAY=5 dupload --to delayed <changes-file></example>
+
+ <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. <ref id="madison"> may be of interest to
+check that information;
+ <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.
+
+ <sect id="pkg-info">Package's information
+ <p>
+
+ <sect1 id="pkg-info-web">On the web
+ <p>
+Each package has several dedicated web pages that contains many
+informations. First <tt>http://&packages-host;/<package></tt>
+will let you discover a presentation of each version of the package
+available in the various distributions. It includes its description,
+the dependencies and some links to download the package.
+ <p>
+The bug tracking system sorts the bugs by package, you can
+watch the bugs of each package at
+<tt>http://&bugs-host;/<package></tt>.
+
+ <sect1 id="madison">The madison utility
+ <p>
+<prgn>madison</prgn> is a command-line utility that is available
+on both <tt>&ftp-master-host;</tt> and <tt>&non-us-host;</tt>. It
+uses a single argument corresponding to a package name. In result
+it displays which version of the package is available for each
+architecture and distribution combination. An example will explain
+it better.
+ <p>
+<example>
+$ madison libdbd-mysql-perl
+libdbd-mysql-perl | 1.2202-4 | stable | source, alpha, arm, i386, m68k, powerpc, sparc
+libdbd-mysql-perl | 1.2216-2 | testing | source, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
+libdbd-mysql-perl | 1.2216-2.0.1 | testing | alpha
+libdbd-mysql-perl | 1.2219-1 | unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
+</example>
+ <p>
+In this example, you can see that the version in unstable differs from
+the version in testing and that there has been a binary-only NMU of the
+package for the alpha architecture. Each time the package has been
+recompiled on most of the architectures.
+
+ <sect id="pkg-tracking-system">The Package Tracking System
+ <p>
+&FIXME; Include some documentation of the PTS. Explain how to use the
+keyword mechanism and what they are for. Explain how to setup an
+automatic forward of cvs commits.
+
<chapt id="pkgs">Managing Packages
<p>
<file>/usr/share/doc/<var>package</var>/changelog.gz</file> for native
packages.
<p>
-The <file>debian/changelog</file> file conform to a certain structure,
+The <file>debian/changelog</file> file conforms to a certain structure,
with a number of different fields. One field of note, the
<em>distribution</em>, is described in <ref id="upload-dist">. More
information about the structure of this file can be found in
directory on <tt>ftp-master</tt> and then move them to
<tt>&us-upload-dir;</tt>.
<p>
-<em>Note:</em> Do not upload to <tt>ftp-master</tt> packages
-containing software that is patent-restricted by the United States
-government, nor any cryptographic packages which belong to
-<em>contrib</em> or <em>non-free</em>. If you can't upload it to
-<tt>ftp-master</tt>, then neither can you upload it to the overseas
-upload queues on <tt>chiark</tt> or <tt>erlangen</tt>. Uploads of
+<em>Note:</em> Do not upload to <tt>ftp-master</tt> cryptographic
+packages which belong to <em>contrib</em> or <em>non-free</em>. Uploads of
such software should go to <tt>non-us</tt> (see <ref
-id="upload-non-us">). If you are not sure whether U.S. patent
-controls or cryptographic controls apply to your package, post a
-message to &email-debian-devel; and ask.
+id="upload-non-us">). Furthermore packages containing code that is
+patent-restricted by the United States government can not be uploaded to
+<tt>ftp-master</tt>; depending on the case they may still be uploaded to
+<tt>non-US/non-free</tt> (it's in non-free because of distribution issues
+and not because of the license of the software). If you can't upload it to
+<tt>ftp-master</tt>, then neither can you upload it to the overseas upload
+queues on <tt>chiark</tt> or <tt>erlangen</tt>. If you are not sure
+whether U.S. patent controls or cryptographic controls apply to your
+package, post a message to &email-debian-devel; and ask.
<p>
You may also find the Debian packages <package>dupload</package> or
<package>dput</package> useful
-when uploading packages. These handy program are distributed with
+when uploading packages. These handy programs are distributed with
defaults for uploading via <prgn>ftp</prgn> to <tt>ftp-master</tt>,
<tt>chiark</tt>, and <tt>erlangen</tt>. They can also be configured to
use <prgn>ssh</prgn> or <prgn>rsync</prgn>. See <manref name="dupload"
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>
the change to the archive may take up to a month to occur. Please be
patient.
<p>
-In any case, you will receive email notification indicating that the
-package has added to the archive, which also indicates which bugs will
+In any case, you will receive an email notification indicating that the
+package has been added to the archive, which also indicates which bugs will
be closed by the upload. Please examine this notification carefully,
checking if any bugs you meant to close didn't get triggered.
<p>
id="nmu-guidelines"> need to be followed.
<p>
Bug fixes to unstable by non-maintainers are also acceptable, but only
-as a last resort or with permission. Try the following steps first,
-and if they don't work, it is probably OK to do an NMU:
+as a last resort or with permission. The following protocol should
+be respected to do an NMU :
<p>
<list>
<item>
-Make sure that the package bug is in the Debian Bug Tracking System
-(BTS). If not, submit a bug.
- <item>
-Email the maintainer, and offer to help fix the package bug. Give it a
-few days.
- <item>
-Go ahead and fix the bug, submitting a patch to the right bug in the
-BTS. Build the package and test it as discussed in <ref
-id="upload-checking">. Use it locally.
- <item>
-Wait a couple of weeks for a response.
+Make sure that the package's bug is in the Debian Bug Tracking System
+(BTS). If not, submit a bug.
<item>
-Email the maintainer, asking if it is OK to do an NMU.
+Wait a few days the response from the maintainer. If you don't get
+any response, you may want to help him by sending the patch that fixes
+the bug. Don't forget to tag the bug with the "patch" keyword.
<item>
+Wait a few more days. If you still haven't got an answer from the
+maintainer, send him a mail announcing your intent to NMU the package.
+Prepare an NMU as described in <ref id="nmu-guidelines">, test it
+carefully on your machine (cf. <ref id="upload-checking">).
Double check that your patch doesn't have any unexpected side effects.
-Make sure your patch is as small and as non-disruptive as it can be.
+Make sure your patch is as small and as non-disruptive as it can be.
<item>
-Wait another week for a response.
+Upload your package to incoming in <tt>DELAYED/7-day</tt> (cf.
+<ref id="delayed-incoming">), send the final patch to the maintainer via
+the BTS, and explain him that he has 7 days to react if he wants to cancel
+the NMU.
<item>
-Go ahead and do the source NMU, as described in <ref
-id="nmu-guidelines">.
+Follow what happens, you're responsible for any bug that you introduced
+with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS)
+to stay informed of the state of the package after your NMU.
</list>
-
-
<sect1 id="nmu-guidelines">How to do a source NMU
<p>
The following applies to porters insofar as they are playing the dual
the <file>debian/changelog</file> file will be used for signing the
changes file.
-
+ <sect1 id="ack-nmu">Acknowledging an NMU
+ <p>
+If one of your packages has been NMUed, you have to incorporate the
+changes in your copy of the sources. This is easy, you just have
+to apply the patch that has been sent to you. Once this is done, you
+have to close the bugs that have been tagged fixed by the NMU. You
+can either close them manually by sending the required mails to the
+BTS or by adding the required <tt>closes: #nnnn</tt> in the changelog
+entry of your next upload.
+ <p>
+In any case, you should not be upset by the NMU. An NMU is not a
+personal attack against the maintainer. It is just the proof that
+someone cares enough about the package and was willing to help
+you in your work. You should be thankful to him and you may want to
+ask him if he would be interested to help you on a more frequent
+basis as co-maintainer or backup maintainer
+(see <ref id="collaborative-maint">).
<sect id="porting">Porting and Being Ported
<package>debootstrap</package> package to create an unstable chroot
environment. Within that chrooted environment, install the
<package>build-essential</package> package and any package
-dependencies mention in <tt>Build-Depends</tt> and/or
+dependencies mentioned in <tt>Build-Depends</tt> and/or
<tt>Build-Depends-Indep</tt>. Finally, try building your package
within that chrooted environment.
<p>
Sometimes the initial porter upload is problematic because the environment
in which the package was built was not good enough (outdated or obsolete
library, bad compiler, ...). Then you may just need to recompile it in
-an updated environment. However, you do have to bump the version number in
+an updated environment. However, you have to bump the version number in
this case, so that the old bad package can be replaced in the Debian archive
(<prgn>katie</prgn> refuses to install new packages if they don't have a
version number greater than the currently available one). Despite the
enhanced to support cross-compiling.
+ <sect id="collaborative-maint">Collaborative maintenance
+ <p>
+&FIXME; Speak about Uploaders: field, about the intelligent use
+of the PTS. Insist that it's a "must have" for base and standard
+packages.
<sect id="archive-manip">
<heading>Moving, Removing, Renaming, Adopting, and Orphaning
Packages</heading>
<p>
-Some archive manipulation operation are not automated in the Debian
+Some archive manipulation operations are not automated in the Debian
upload process. These procedures should be manually followed by
maintainers. This chapter gives guidelines in what to do in these
cases.
package. When invoked as <tt>apt-cache showpkg
<var>package</var></tt>, the program will show details for
<var>package</var>, including reverse depends.
+ <p>
+Once the package has been removed, the package's bugs should be handled.
+They should either be reassigned to another package in the case where
+the actual code has evolved into another package (e.g. <tt>libfoo12</tt>
+was removed because <tt>libfoo13</tt> supersedes it) or closed if the
+software is simply no more part of Debian.
<sect2>Removing packages from <tt>Incoming</tt>
<p>
name="Debian Policy Manual"> for details). Once you've uploaded
that package, and the package has moved into the archive, file a bug
against <tt>ftp.debian.org</tt> asking to remove the package with the
-obsolete name.
+obsolete name. Do not forget to properly reassign the package's bugs
+at the same time.
<sect1 id="orphaning">Orphaning a package
<p>
If you can no longer maintain a package, you need to inform the others
about that, and see that the package is marked as orphaned.
-you should set the package maintainer to <tt>Debian QA Group
+You should set the package maintainer to <tt>Debian QA Group
&orphan-address;</tt> and submit a bug report
against the pseudo package <package>wnpp</package>. The bug report should be
titled <tt>O: <var>package</var> -- <var>short description</var></tt>
If the package is especially crucial to Debian, you should instead submit
a bug against <tt>wnpp</tt> and title it <tt>RFA: <var>package</var> --
<var>short description</var></tt> and set its severity to
-<em>important</em>. Definitely copy the message to debian-devel in this
-case, as described above.
+<em>important</em>. <tt>RFA</tt> stands for <em>Request For Adoption</em>.
+Definitely copy the message to debian-devel in this case, as described
+above.
<p>
Read instructions on the <url id="&url-wnpp;" name="WNPP web pages">
for more information.
However, without their assent, you may not take over the package.
Even if they ignore you, that is still not grounds to take over a
package. If you really feel that a maintainer has gone AWOL (absent
-without leave), post a query to &email-debian-private;.
+without leave), post a query to &email-debian-private;. You may also
+inform the QA group (cf. <ref id="mia-qa">).
<p>
If you take over an old package, you probably want to be listed as the
package's official maintainer in the bug system. This will happen
automatically once you upload a new version with an updated
<tt>Maintainer:</tt> field, although it can take a few hours after the
upload is done. If you do not expect to upload a new version for a while,
-send an email to &email-override; so that bug reports will go to you
-right away.
-
+you can use <ref id="pkg-tracking-system"> to get the bug reports. However,
+make sure that the old maintainer is not embarassed by the fact that
+he will continue to receive the bugs during that time.
<sect id="bug-handling">Handling package bugs
If you want to be a good maintainer, you should periodically check the
<url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
packages. The BTS contains all the open bugs against your packages.
+You can check them by browsing this page:
+<tt>http://&bugs-host;/yourlogin@debian.org</tt>.
<p>
Maintainers interact with the BTS via email addresses at
<tt>bugs.debian.org</tt>. Documentation on available commands can be
# 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.
<sect1 id="bug-answering">Responding to bugs
<p>
-Make sure that any discussions you have about bugs are sent both to
+Make sure that any discussion 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>). If you're writing a new
+mail and you don't remember the submitter email address, you can
+use the <email>123-submitter@bugs.debian.org</email> email to
+contact the submitter <em>and</em> to record your mail within the
+bug log (that means you don't need to send a copy of the mail to
<email>123@bugs.debian.org</email>).
<p>
You should <em>never</em> close bugs via the bug server <tt>close</tt>
As a package maintainer, you will often find bugs in other packages or
have bugs reported against your packages which are actually bugs in
other packages. The <url id="&url-bts-control;" name="BTS
-instructions"> document the technical operation of the BTS, such as
+instructions"> document the technical operations of the BTS, such as
how to file, reassign, merge, and tag bugs. This section contains
some guidelines for managing your own bugs, based on the collective
Debian developer experience.
/closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
</example>
-The author prefers the <tt>closes: #<var>XXX</var>)</tt> syntax, as
+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>
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>
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>
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>
+Whatever the reason, it is a pain to lookup the email address of the
+maintainer of the package that you are interested in. Fortunately, you
+can use a simple email alias : <tt><package>@&packages-host;</tt>.
+<tt><package></tt> can be 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>@&pts-host;</tt>
+email address.
<sect id="newmaint">
<heading>Interacting with prospective Debian developers</heading>
<p>
-Debian's success depends on it's ability to attract and retain new and
+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
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 the how the applicant is
+be their sponsor. That way you can also verify how the applicant is
handling the 'Tasks and Skills' part of their application.
~ianmdlvl / developers-reference.git / blobdiff