X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=a00cabd3ace8f97d7fcf6ee63b1a026c12149ca0;hb=0705951199dd03a594900f56aa58225d68314ba6;hp=95f5bc35f33b2e9689aa592fdbde4b46a412ac26;hpb=b371924c48cc2132db092d34c6c853d55f411f0c;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 95f5bc3..a00cabd 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -7,7 +7,7 @@ %dynamicdata; - + @@ -58,6 +58,7 @@ writing to the &fsf-addr;.
If you want to print this reference, you should use the
If you wish to be a mentor and/or sponsor, more information is
available in .
@@ -231,12 +232,39 @@ You can use some other implementation of OpenPGP as well. Note that
OpenPGP is an open standard based on
-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.
+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.
+
+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
+5B00 C96D 5D54 AEE1 206B AF84 DE7A AF6E 94C0 9C7F
+then it's a v4 key.
+
+Another possibility is to pipe the key into
+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.
+
If your public key isn't on public key servers such as &pgp-keyserv;,
please read the documentation available locally in &file-keyservs;.
@@ -309,13 +337,12 @@ can update the Debian key ring by sending your key to the key server at
&keyserver-host;.
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
+
The same key extraction routines discussed in
apply.
@@ -436,7 +463,7 @@ the following steps:
There are other additional channels dedicated to specific subjects.
-#debian-bugs is used for coordinating bug squash parties.
+#debian-bugs is used for coordinating bug squashing parties.
#debian-boot is used to coordinate the work on the debian-installer.
#debian-doc is
occasionally used to talk about documentation, like the document you are
@@ -579,7 +606,7 @@ Channels dedicated to Debian also exist on other IRC networks, notably on
the
-To get a cloak on freenode, you send Göran Weinholt <weinholt@debian.org>
+To get a cloak on freenode, you send Jörg Jaspert <joerg@debian.org>
a signed mail where you tell what your nick is.
Put "cloak" somewhere in the Subject: header.
The nick should be registered:
@@ -669,17 +696,10 @@ an email to &email-ftpmaster;, but also see the procedures in
-The non-US server, non-us.debian.org,
-holds the canonical copy of the non-US part of the Debian archive.
-If you need to upload a package into one of the non-US sections, upload it
-to this server; see .
-
-Problems with the non-US package archive should generally be submitted as
-bugs against the
@@ -710,8 +730,7 @@ whereas on other hosts it won't.
Usually the only reason to use a different host is when you need to publish
materials subject to the U.S. export restrictions, in which case you can use
-one of the other servers located outside the United States, such as the
-aforementioned non-us.debian.org.
+one of the other servers located outside the United States.
Send mail to &email-debian-devel; if you have any questions.
@@ -996,7 +1015,7 @@ stable distribution is incremented (e.g., ‘3.0’ becomes
‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and
so forth).
Please refer to
-
Note that development under unstable continues during the
@@ -1028,8 +1047,8 @@ distribution.
These are the
If there is a chance that the software could do grave damage to a system,
@@ -1068,8 +1087,10 @@ to finally get them closed.
Every released Debian distribution has a code name: 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
@@ -1131,8 +1152,7 @@ have accounts on these machines.
The Incoming system is responsible for collecting updated packages and
installing them in the Debian archive. It consists of a set of
-directories and scripts that are installed both on &ftp-master-host;
-and &non-us-host;.
+directories and scripts that are installed on &ftp-master-host;.
Packages are uploaded by all the maintainers into a directory called
You can control your subscription(s) to the PTS by sending
-various commands to
+The
Once you are subscribed to a package, you will get the mails sent to
@@ -1543,8 +1587,23 @@ by Debian, facilitate contributions from external developers to projects
started by Debian, and help projects whose goals are the promotion of Debian
or its derivatives.
+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.
+
For more information please visit
+
+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
+
@@ -1670,6 +1729,11 @@ Downgrade the package to the previous version (if one exists) — this
tests the
+Please notice that, in non-native packages, permissions on files that are not
+present in the .orig.tar.gz will not be preserved, as diff does not store file
+permissions in the patch.
-
-Note: Do not upload to ftp-master cryptographic
-packages which belong to contrib or non-free. Uploads of
-such software should go to non-us (see ). Furthermore packages containing code that is
-patent-restricted by the United States government cannot be uploaded to
-ftp-master; depending on the case they may still be uploaded to
-
You may also find the Debian packages or
useful
when uploading packages. These handy programs help automate the
@@ -1821,41 +1875,7 @@ and the Debian package .
-Note: non-us is currently not processed any more.
-
-As discussed above, export controlled software should not be uploaded
-to ftp-master. Instead, upload the package with anonymous FTP
-to
-Note that U.S. residents or citizens are subject to restrictions on
-export of cryptographic software. As of this writing, U.S. citizens
-are allowed to export some cryptographic software, subject to
-notification rules by the U.S. Department of Commerce. However, this
-restriction has been waived for software which is already available
-outside the U.S. Therefore, any cryptographic software which belongs
-in the main section of the Debian archive and does not depend
-on any package outside of main (e.g., does not depend on
-anything in non-US/main) can be uploaded to ftp-master
-or its queues, described above.
-
-Debian policy does not prevent upload to non-US by U.S. residents or
-citizens, but care should be taken in doing so. It is recommended that
-developers take all necessary steps to ensure that they are not
-breaking current US law by doing an upload to non-US, including
-consulting a lawyer.
-
-For packages in non-US/main, non-US/contrib,
-developers should at least follow the
-This section is for information only and does not constitute legal
-advice. Again, it is strongly recommended that U.S. citizens and
-residents consult a lawyer before doing uploads to non-US.
+Note: non-us was discontinued with release of sarge.
-The scp queues on ftp-master, non-us, and security are mostly unusable
+The scp queues on ftp-master, and security are mostly unusable
due to the login restrictions on those hosts.
The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are
@@ -1954,7 +1974,7 @@ or priority for your package be changed from the old section or
priority to the new one. Be sure to explain your reasoning.
For more information about override files, see
Note that the Section field describes both the section as
@@ -2129,9 +2149,9 @@ read .
-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.
@@ -2444,7 +2464,7 @@ Once you have created and tested the new package and it has been
approved by the security team, it needs to be uploaded so that it can
be installed in the archives. For security uploads, the place to
upload to is
-ftp://security.debian.org/pub/SecurityUploadQueue/ .
+ftp://security-master.debian.org/pub/SecurityUploadQueue/ .
Once an upload to the security queue has been accepted, the package
@@ -2500,7 +2520,9 @@ override file updated, as described in .
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 ftp.debian.org 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 unstable and experimental. Packages
are not removed from testing directly. Rather, they will be
@@ -2767,12 +2789,22 @@ new Debian version, there is no corresponding source update. If you
get this wrong, the archive maintainers will reject your upload (due
to lack of corresponding source code).
-The ``magic'' for a recompilation-only NMU is triggered by using the
-third-level number on the Debian part of the version. For instance,
-if the latest version you are recompiling against was version
-``2.9-3'', your NMU should carry a version of ``2.9-3.0.1''. If the
-latest version was ``3.4-2.1'', your NMU should have a version number
-of ``3.4-2.1.1''.
+The ``magic'' for a recompilation-only NMU is triggered by using a
+suffix appended to the package version number,
+following the form b<number>.
+For instance, if the latest version you are
+recompiling against was version ``2.9-3'', your NMU should carry a
+version of ``2.9-3+b1''. If the latest version was ``3.4+b1'' (i.e, a
+native package with a previous recompilation NMU), your NMU should have
+a version number of ``3.4+b2''.
+
+
Similar to initial porter uploads, the correct way of invoking
+The buildds admins of each arch can be contacted by the mail address
+$arch@buildd.debian.org.
+
+
+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 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.
+
+In order to prevent broken packages from being uploaded to the archive, and
+wasting buildd time, you need to do a few things:
+
+
+First, make sure your package does 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.
+
+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.
+
+In order to prevent autobuilders from needlessly trying to build your
+package, it must be included in
+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 their removal by filing a bug against
+
-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.
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.
@@ -3082,7 +3164,10 @@ new version, the maintainer needs to ensure that the new upstream version
really fixes each problem that was fixed in the non-maintainer release.
In addition, the normal maintainer should always retain the
-entry in the changelog file documenting the non-maintainer upload.
+entry in the changelog file documenting the non-maintainer upload --
+and of course, also keep the changes.
+If you revert some of the changes,
+please reopen the relevant bug reports.
Now, the more complex part happens: Britney tries to update testing with
the valid candidates; first, each package alone, and then larger and even
-larger sets of packages together. Each try is accepted if unstable is not
+larger sets of packages together. Each try is accepted if testing is not
more uninstallable after the update than before. (Before and after this part,
some hints are processed; but as only release masters can hint, this is
probably not so important for you.)
@@ -3533,9 +3618,11 @@ it's usually the file maintainers spend the most time on.
The rationale for using helper scripts in
-
Be careful to avoid spelling and grammar mistakes. Ensure that you
-spell-check it.
Users usually expect these questions to be answered in the package
description:
@@ -3805,7 +3893,10 @@ Note that we expect this field will eventually be replaced by a proper
It is an old tradition to acknowledge bugs fixed in non-maintainer
-uploads in the first changelog entry of the proper maintainer upload,
-for instance, in a changelog entry like this:
-
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).
@@ -4098,7 +4183,7 @@ Most questions should use medium and low priorities.
Most Debian package maintainers are not native English speakers. So,
writing properly phrased templates may not be easy for them.
-Please use (and abuse) debian-l10n-english@lists.debian.org mailing
+Please use (and abuse) &email-debian-l10n-english; mailing
list. Have your templates proofread.
Badly written templates give a poor image of your package, of your
@@ -4112,10 +4197,10 @@ doing so, try to balance between verbosity and simplicity.
Debconf templates may be translated. Debconf, along with its sister
-package po-debconf offers a simple framework for getting
+package
-Please use gettext-based templates. Install po-debconf on your
+Please use gettext-based templates. Install
@@ -4128,10 +4213,57 @@ additional uploads. If you use gettext-based templates, the
translator's name and e-mail addresses are mentioned in the po files
headers.
+The use of the
If in doubt, you may also contact the translation team for a given
language (debian-l10n-xxxxx@lists.debian.org), or the
-debian-i18n@lists.debian.org mailing list.
+&email-debian-i18n; mailing list.
+
+Calls for translations posted to
+&email-debian-i18n; with the
+When the text of a debconf template is corrected and you are
+sure that the change does not affect
+translations, please be kind to translators and unfuzzy their
+translations.
+
+If you don't do so, the whole template will not be translated as long
+as a translator will send you an update.
+
+To unfuzzy translations, you can proceed the following way:
+
Templates text should not make reference to widgets belonging to some
@@ -4139,6 +4271,12 @@ debconf interfaces. Sentences like "If you answer Yes..." have no
meaning for users of graphical interfaces which use checkboxes for
boolean questions.
+String templates should also avoid mentioning the default values in
+their description. First, because this is redundant with the values
+seen by the users. Also, because these default values may be different
+from the maintainer choices (for instance, when the debconf database
+was preseeded).
+
More generally speaking, try to avoid referring to user actions.
Just give facts.
@@ -4223,7 +4361,7 @@ usual blue one).
-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.
The short description should be kept short (50 characters or so) so
@@ -4506,7 +4644,7 @@ should retrieve the source package.
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.
@@ -4637,7 +4775,7 @@ to your short description. If you are looking for examples, just run:
There are two kinds of original source tarballs: Pristine source
and repackaged upstream source.
The defining characteristic of a pristine source tarball is that the
@@ -4645,7 +4783,7 @@ The defining characteristic of a pristine source tarball is that the
distributed by the upstream author.
You should upload packages with a pristine source
@@ -4966,7 +5104,7 @@ a source or a binary package.
+
+