<!ENTITY % versiondata SYSTEM "version.ent"> %versiondata;
<!-- common, language independent entities -->
<!ENTITY % commondata SYSTEM "common.ent" > %commondata;
+ <!ENTITY % dynamicdata SYSTEM "dynamic.ent" > %dynamicdata;
<!-- CVS revision of this document -->
- <!ENTITY cvs-rev "$Revision: 1.257 $">
+ <!ENTITY cvs-rev "$Revision: 1.266 $">
<!-- if you are translating this document, please notate the CVS
revision of the original developer's reference in cvs-en-rev -->
<copyright>
<copyrightsummary>
-copyright © 2004 Andreas Barth</copyrightsummary>
+copyright © 2004—2005 Andreas Barth</copyrightsummary>
<copyrightsummary>
copyright © 1998—2003 Adam Di Carlo</copyrightsummary>
<copyrightsummary>
id="&url-gpl;" name="the GNU web site">. You can also obtain it by
writing to the &fsf-addr;.
+<![ %htmltext [
+ <p>
+If you want to print this reference, you should use the <url
+id="developers-reference.pdf" name="pdf version">.
+]]>
+
<toc detail="sect1">
<chapt id="scope">Scope of This Document
get started. Finally, if you are interested in documentation or
Quality Assurance (QA) work you can join maintainers already working on
these tasks and submit patches and improvements.
+
+
+ <sect id="mentors">Debian mentors and sponsors
+ <p>
+The mailing list &email-debian-mentors; has been set up for novice
+maintainers who seek help with initial packaging and other
+developer-related issues. Every new developer is invited to subscribe
+to that list (see <ref id="mailing-lists"> for details).
+ <p>
+Those who prefer one-on-one help (e.g., via private email) should also
+post to that list and an experienced developer will volunteer to help.
+ <p>
+In addition, if you have some packages ready for inclusion in Debian,
+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.
+<!-- FIXME - out of order
+Those who are seeking a
+sponsor can request one at <url id="&url-sponsors;">.
+-->
+Please read the
+inofficial debian-mentors FAQ at <url id="&url-mentors;"> first.
+ <p>
+If you wish to be a mentor and/or sponsor, more information is
+available in <ref id="newmaint">.
<sect id="registering">Registering as a Debian developer
accounts on our servers and let them upload packages.
<p>
Before you actually register you should have shown that you can do
-competent work and will be a good contributor. You can show this by
-submitting patches through the Bug Tracking System or having a package
+competent work and will be a good contributor.
+You show this by submitting patches through the Bug Tracking System
+and having a package
sponsored by an existing maintainer for a while. Also, we expect that
contributors are interested in the whole project and not just in
maintaining their own packages. If you can help other maintainers by
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="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 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.)
+a maintainer close to you.
+(If there is no Debian maintainer close to you,
+alternative ways to pass the ID check may be permitted
+as an absolute exception on a case-by-case-basis.
+See the <url id="&url-newmaint-id;" name="identification page">
+for more informations.)
<p>
If you do not have an OpenPGP key yet, generate one. Every developer
OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC
2440">.
<p>
-<!-- FIXME: DSS is not exactly equivalent to DSA, is it? -->
-The recommended public key algorithm for use in Debian development
-work is DSA (sometimes called ``DSS'' or ``DH/ElGamal'').
-Other key types may be used, however. Your key length must be at least 1024
+You need a type 4 key for use in Debian Development.
+Your key length must be at least 1024
bits; there is no reason to use a smaller key, and doing so would be
-much less secure. Your key must be signed with at least your own user
+much less secure. Your key must be signed with your own user
ID; this prevents user ID tampering. <prgn>gpg</prgn> does this
automatically.
<p>
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.
-&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
+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>
a lot of time later on.
- <sect id="mentors">Debian mentors and sponsors
- <p>
-The mailing list &email-debian-mentors; has been set up for novice
-maintainers who seek help with initial packaging and other
-developer-related issues. Every new developer is invited to subscribe
-to that list (see <ref id="mailing-lists"> for details).
- <p>
-Those who prefer one-on-one help (e.g., via private email) should also
-post to that list and an experienced developer will volunteer to help.
- <p>
-In addition, if you have some packages ready for inclusion in Debian,
-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.
-<!-- FIXME - out of order
-Those who are seeking a
-sponsor can request one at <url id="&url-sponsors;">.
--->
-Please read the
-inofficial debian-mentors FAQ at <url id="&url-mentors;"> first.
- <p>
-If you wish to be a mentor and/or sponsor, more information is
-available in <ref id="newmaint">.
-
-
<chapt id="developer-duties">Debian Developer's Duties
<sect id="user-maint">Maintaining your Debian information
<tt>&keyserver-host;</tt>.
<p>
If you need to add a completely new key or remove an old key, you need
-to get the new key signed by another developer. After this, a mail
-signed by another developer listing your account name, the keyids
-of the old and of the new key and the reason should be send to
-&email-debian-keyring;. If the old key is compromised or invalid, you
+to get the new key signed by another developer.
+If the old key is compromised or invalid, you
also have to add the revocation certificate. If there is no real
-reason for a new key, the Keyring Maintainers will only accept it if
-it's more secure and connected to the old key.
+reason for a new key, the Keyring Maintainers might reject the new key.
+Details can be found at
+<url id="http://keyring.debian.org/replacing_keys.html">.
<p>
The same key extraction routines discussed in <ref id="registering">
apply.
tightened. Packages which are too buggy are removed. No changes are
allowed into <em>testing</em> except for bug fixes. After some time
has elapsed, depending on progress, the <em>testing</em> distribution
-goes into a `deep freeze', when no changes are made to it except those
-needed for the installation system. This is called a “test cycle”,
-and it can last up to two weeks. There can be several test cycles,
-until the distribution is prepared for release, as decided by the
-release manager. At the end of the last test cycle, the
-<em>testing</em> distribution is renamed to <em>stable</em>,
-overriding the old <em>stable</em> distribution, which is removed at
-that time (although it can be found at <tt>&archive-host;</tt>).
+is frozen even further.
+Details of the handling of the testing distribution are published
+by the Release Team on debian-devel-announce.
+After the open issues are solved to the satisfaction of the Release Team,
+the distribution is released.
+Releasing means
+that <em>testing</em> is renamed to <em>stable</em>,
+and a new copy is created for the new <em>testing</em>,
+and the previous <em>stable</em> is renamed to <em>oldstable</em>
+and stays there until it is finally archived.
+On archiving, the contents are moved to <tt>&archive-host;</tt>).
<p>
This development cycle is based on the assumption that the
<em>unstable</em> distribution becomes <em>stable</em> after passing a
stable distribution is incremented (e.g., ‘3.0’ becomes
‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and
so forth).
+Please refer to
+<qref="upload-stable">uploads to the <em>stable</em> distribution</qref>
+for details.
<p>
Note that development under <em>unstable</em> continues during the
freeze period, since the <em>unstable</em> distribution remains in
</example>
<p>
Think twice before adding a news item to the PTS because you won't be able
-to remove it later and you wan't be able to edit it either. The only thing
+to remove it later and you won't be able to edit it either. The only thing
that you can do is send a second news item that will deprecate the
information contained in the previous one.
started by Debian, and help projects whose goals are the promotion of Debian
or its derivatives.
<p>
+All Debian developers automatically have an account on Alioth.
+They can activate it by using the recover password facility.
+External developers can request guest accounts on Alioth.
+ <p>
For more information please visit <url id="&url-alioth;">.
+ <sect id="developer-misc">Goodies for Developers
+ <p>
+ <sect1 id="lwn">LWN Subscriptions
+ <p>
+Since October of 2002, HP has sponsored a subscription to LWN for all
+interested Debian developers.
+
+Details on how to get access to this benefit are in
+<url id="http://lists.debian.org/debian-devel-announce/2002/10/msg00018.html">.
+
+
<chapt id="pkgs">Managing Packages
<p>
priority to the new one. Be sure to explain your reasoning.
<p>
For more information about <em>override files</em>, see <manref
-name="dpkg-scanpackages" section="8"> and
+name="dpkg-scanpackages" section="1"> and
<url id="&url-bts-devel;#maintincorrect">.
<p>
Note that the <tt>Section</tt> field describes both the section as
the bug to the right package. If you don't know which package it should
be reassigned to, you should ask for help on
<qref id="irc-channels">IRC</qref> or on &email-debian-devel;.
+Please make sure that the maintainer(s) of the package
+the bug is reassigned to
+know why you reassigned it.
<p>
Sometimes you also have to adjust the severity of the bug so that it
matches our definition of the severity. That's because people tend to
general interest (for instance, a flavor of Debian built with <prgn>gcc</prgn>
bounds checking). It will also enable Debian to recompile entire
distributions quickly.
- </sect2>
+ <p>
+The buildds admins of each arch can be contacted by the mail address
+$arch@buildd.debian.org.
+
+ <sect1 id="packages-arch-specific">When your package is <em>not</em> portable
+ <p>
+Some packages still have issues with building and/or working on some
+of the architectures supported by Debian, and cannot be ported at all,
+or not with a reasonable amount of time. An example is a package that
+is SVGA-specific (only i386), or uses other hardware-specific features
+not supported on all architectures.
+ <p>
+In order to prevent broken packages from being uploaded to the archive, and
+wasting buildd time, you need to do a few things:
+ <p>
+ <list>
+ <item>
+ <p>
+First, make sure your package <em>does</em> fail to build on
+architectures that it cannot support.
+There are a few ways to achieve this.
+The preferred way is to have a small testsuite during build time
+that will test the functionality, and fail if it doesn't work.
+This is a good idea anyway,
+as this will prevent (some) broken uploads on all architectures,
+and also will allow the package to build
+as soon as the required functionality is available.
+ <p>
+Additionally, if you believe the list of supported architectures is
+pretty constant, you should change 'any' to a list of supported
+architectures in debian/control. This way, the build will fail also,
+and indicate this to a human reader without actually trying.
+ <item>
+ <p>
+In order to prevent autobuilders from needlessly trying to build your
+package, it must be included in <file>packages-arch-specific</file>, a
+list used by the <prgn>wanna-build</prgn> script.
+The current version is available as
+<url id="http://cvs.debian.org/srcdep/Packages-arch-specific?rev=HEAD&cvsroot=dak&content-type=text/vnd.viewcvs-markup">;
+please see the top of the file for whom to contact for changes.
+ </list>
+ <p>
+Please note that it is insufficient to only add your package to
+Packages-arch-specific
+without making it fail to build on unsupported architectures:
+A porter or any other person trying to build your package might
+accidently upload it without noticing it doesn't work.
+If in the past some binary packages were uploaded on unsupported architectures,
+request there removal by filing a bug against
+<package>ftp.debian.org</package>
<sect id="nmu">Non-Maintainer Uploads (NMUs)
have to close the bugs that have been tagged fixed by the NMU. The easiest
way is to use the <tt>-v</tt> option of <prgn>dpkg-buildpackage</prgn>,
as this allows you to include just all changes since your last maintainer
-upload. Alternativly, you
+upload. Alternatively, you
can 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.
to the Bug Tracking System. Maintainers almost always appreciate
quality patches and bug reports.
+ <sect1 id="nmu-katie">How dak detects NMUs
+ <p>
+Whether an upload is treated as an NMU or as a maintainer upload by
+the archive scripts and the bugtracking system (see <ref
+id="nmu-patch">) is <em>not</em> decided by looking at the version
+number (see <ref id="nmu-version">). Instead, an upload is handled as
+an NMU if the maintainer address in the <tt>.changes</tt> file is not
+binary the same as the address in the <tt>Maintainer</tt> field, or
+any of the addresses the <tt>Uploaders</tt> field, of the <tt>dsc</tt>
+file, and also if the maintainer address is not special (i.e. it is
+not set to the QA Group address).
+
<sect1 id="nmu-terms">Terminology
<p>
There are two new terms used throughout this section: ``binary-only NMU''
<heading>Updates from unstable</heading>
<p>
The scripts that update the <em>testing</em> distribution are run each
-day after the installation of the updated packages. They generate the
+day after the installation of the updated packages;
+these scripts are called <em>britney</em>.
+They generate the
<file>Packages</file> files for the <em>testing</em> distribution, but
they do so in an intelligent manner; they try to avoid any inconsistency
and to use only non-buggy packages.
<sect2>Do not use first person
<p>
You should avoid the use of first person ("I will do this..." or "We
-recommend..."). The computer is not a person and the Debconf tempaltes
+recommend..."). The computer is not a person and the Debconf templates
do not speak for the Debian developers. You should use neutral
construction and often the passive form. Those of you who already
wrote scientific publications, just write your templates like you
out all the bugs you submitted, you just have to visit
<tt>http://&bugs-host;/from:<var><your-email-addr></var></tt>.
- <sect1 id="submit-many-bugs">Reporting lots of bugs at once
+ <sect1 id="submit-many-bugs">Reporting lots of bugs at once (mass bug filing)
<p>
Reporting a great number of bugs for the same problem on a great
number of different packages — i.e., more than 10 — is a deprecated
~ianmdlvl / developers-reference.git / blobdiff