<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.101 $">
+ <!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
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>
<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>.
<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 publicly
+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> files for example) have been made,
-a special script is called to ask all the primary mirrors to update
+<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>
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 your upload once it has been accepted.
- <p>
+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
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
<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"
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.
<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
<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>
<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 the Package Tracking
-System. You can do so by using the <tt><package>@&pts-host;</tt>
-address.
+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">
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