<!ENTITY % dynamicdata SYSTEM "dynamic.ent" > %dynamicdata;
<!-- CVS revision of this document -->
- <!ENTITY cvs-rev "$Revision: 1.284 $">
+ <!ENTITY cvs-rev "$Revision: 1.287 $">
<!-- if you are translating this document, please notate the CVS
revision of the original developer's reference in cvs-en-rev -->
sponsor can request one at <url id="&url-sponsors;">.
-->
Please read the
-inofficial debian-mentors FAQ at <url id="&url-mentors;"> first.
+unofficial 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">.
OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC
2440">.
<p>
-You need a type 4 key for use in Debian Development.
+You need a version 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 your own user
-ID; this prevents user ID tampering. <prgn>gpg</prgn> does this
-automatically.
+much less secure.
+<footnote>Version 4 keys are keys conforming to
+the OpenPGP standard as defined in RFC 2440. Version 4 is the key
+type that has always been created when using GnuPG. PGP versions
+since 5.x also could create v4 keys, the other choice having beein
+pgp 2.6.x compatible v3 keys (also called "legacy RSA" by PGP).
+<p>
+Version 4 (primary) keys can either use the RSA or the DSA algorithms,
+so this has nothing to do with GnuPG's question about "which kind
+of key do you want: (1) DSA and Elgamal, (2) DSA (sign only), (5)
+RSA (sign only). If you don't have any special requirements just pick
+the defailt.
+<p>
+The easiest way to tell whether an existing key is a v4 key or a v3
+(or v2) key is to look at the fingerprint:
+Fingerprints of version 4 keys are the SHA-1 hash of some key matieral,
+so they are 40 hex digits, usually grouped in blocks of 4. Fingerprints
+of older key format versions used MD5 and are generally shown in blocks
+of 2 hex digits. For example if your fingerprint looks like
+<tt>5B00 C96D 5D54 AEE1 206B AF84 DE7A AF6E 94C0 9C7F</tt>
+then it's a v4 key.
+<p>
+Another possibility is to pipe the key into <prgn>pgpdump</prgn>,
+which will say something like "Public Key Packet - Ver 4".
+<p>
+Also note that your key must be self-signed (i.e. it has to sign
+all its own user IDs; this prevents user ID tampering). All
+modern OpenPGP software does that automatically, but if you
+have an older key you may have to manually add those signatures.
+</footnote>
<p>
If your public key isn't on public key servers such as &pgp-keyserv;,
please read the documentation available locally in &file-keyservs;.
all the files.
<p>
There are other additional channels dedicated to specific subjects.
-<em>#debian-bugs</em> is used for coordinating bug squash parties.
+<em>#debian-bugs</em> is used for coordinating bug squashing parties.
<em>#debian-boot</em> is used to coordinate the work on the debian-installer.
<em>#debian-doc</em> is
occasionally used to talk about documentation, like the document you are
<p>
Every released Debian distribution has a <em>code name</em>: Debian
1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0,
-`hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; and Debian 3.0, `woody'. There is also
-a ``pseudo-distribution'', called `sid', which is the current
+`hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; Debian 3.0, `woody';
+Debian 3.1, "sarge";
+Debian (number needs to be determined), "etch".
+There is also a ``pseudo-distribution'', called `sid', which is the current
`unstable' distribution; since packages are moved from `unstable' to
`testing' as they approach stability, `sid' itself is never released.
As well as the usual contents of a Debian distribution, `sid' contains
<sect1 id="upload-bugfix">When bugs are closed by new uploads
<p>
-As bugs and problems are fixed your packages, it is your
-responsibility as the package maintainer to close the bug. However,
-you should not close the bug until the package which fixes the bug has
+As bugs and problems are fixed in your packages, it is your
+responsibility as the package maintainer to close these bugs. However,
+you should not close a bug until the package which fixes the bug has
been accepted into the Debian archive. Therefore, once you get
notification that your updated package has been installed into the
archive, you can and should close the bug in the BTS.
If for some reason you want to completely remove a package (say, if it
is an old compatibility library which is no longer required), you
need to file a bug against <tt>ftp.debian.org</tt> asking that the
-package be removed. Make sure you indicate which distribution the
+package be removed;
+as all bugs, this bug should normally have normal severity.
+Make sure you indicate which distribution the
package should be removed from. Normally, you can only have packages
removed from <em>unstable</em> and <em>experimental</em>. Packages
are not removed from <em>testing</em> directly. Rather, they will be
<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
+or not within 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>
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">;
+<url id="http://cvs.debian.org/srcdep/Packages-arch-specific?cvsroot=dak">;
please see the top of the file for whom to contact for changes.
</list>
<p>
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
+request their removal by filing a bug against
<package>ftp.debian.org</package>
However, aesthetic changes must <em>not</em> be made in a non-maintainer
upload.
<p>
-And please remember the Hippocratic Oath: "Above all, do no harm."
-It is better if a package has an grave bug open, than if a not working
-patch was applied, and the bug is only hidden now but not resolved.
+And please remember the Hippocratic Oath: "Above all, do no harm." It
+is better to leave a package with an open grave bug than applying a
+non-functional patch, or one that hides the bug instead of resolving
+it.
<sect1 id="nmu-guidelines">How to do a NMU
for a package to enter testing is through unstable.
<p>
For the stable distribution, please take extra care. Of course, the release
-managers may also change the rules here. Please verify before upload that
+managers may also change the rules here. Please verify before you upload that
all your changes are OK for inclusion into the next stable release by the
release manager.
<p>
<sect1 id="helper-scripts">Helper scripts
<p>
The rationale for using helper scripts in <file>debian/rules</file> is
-that lets maintainers use and share common logic among many packages.
+that they let maintainers use and share common logic among many packages.
Take for instance the question of installing menu entries: you need to
put the file into <file>/usr/lib/menu</file> (or
<file>/usr/lib/menu</file> for executable binary menufiles, if this is needed),
patches. See the package <package>dbs</package> for more information and
<package>hello-dbs</package> for an example.
<p>
-<prgn>dpatch</prgn> also provides these facilities, but it's intented to be
+<prgn>dpatch</prgn> also provides these facilities, but it's intended to be
even easier to use. See the package <package>dpatch</package> for
documentation and examples (in <file>/usr/share/doc/dpatch</file>).
<file>debian/control</file> field understood by <prgn>dpkg</prgn> and
<tt>&packages-host;</tt>. If you don't want to bother migrating the
home page from the description to this field, you should probably wait
-until that is available.</p>
+until that is available.
+ Please make sure that this line matches the regular expression
+ <tt>/^ Homepage: [^ ]*$/</tt>,
+ as this allows <file>packages.debian.org</file> to parse it correctly.</p>
</sect1>
</sect>
<p>
These guidelines include some writing style and typography
recommendations, general considerations about debconf usage as well as
-more specific recommendations for some parts of the distribution (for
-instance, the installation system).
+more specific recommendations for some parts of the distribution (the
+installation system for instance).
<sect1>Do not abuse debconf
<p>
<sect2>Description: short and extended description
<p>
-Templates descriptions have two parts: short and extended. The short
+Template descriptions have two parts: short and extended. The short
description is in the "Description:" line of the template.
<p>
The short description should be kept short (50 characters or so) so
<p>
Policy specifies that documentation should be shipped in HTML format.
We also recommend shipping documentation in PDF and plain text format if
-convenient and quality output is possible. However, it is generally
+convenient and if output of reasonable quality is possible. However, it is generally
not appropriate to ship plain text versions of documentation whose source
format is HTML.</p>
<p>
distributed by the upstream author.
<footnote>
We cannot prevent upstream authors from changing the tarball
-they distribute without also upping the version number, so
+they distribute without also incrementing the version number, so
there can be no guarantee that a pristine tarball is identical
to what upstream <em>currently</em> distributing at any point in
time. All that can be expected is that it is identical to
<p>
You may also be interested in 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-name>@&pts-host;</tt>
+You can do so by using the <tt><package>@&pts-host;</tt>
email address.
<!-- FIXME: moo@packages.d.o is easily confused with moo@packages.qa.d.o -->
avoid the chaos resulting in having several versions of the same document in
bug reports.
<p>
-The best solution is to fill a regular bug containing the translation against
+The best solution is to file a regular bug containing the translation against
the package. Make sure to use the 'PATCH' tag, and to not use a severity higher
than 'wishlist', since the lack of translation never prevented a program from
running.
<package>debhelper</package>.
<p>
The consensus is that <package>debmake</package> is now deprecated in
-favor of <package>debhelper</package>. However, it's not a bug to use
-<package>debmake</package>.
+favor of <package>debhelper</package>. It is a bug to use
+<package>debmake</package> in new packages. New packages using
+<package>debmake</package> will be rejected from the archive.
</sect1>
<sect1 id="dh-make">