X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=a00cabd3ace8f97d7fcf6ee63b1a026c12149ca0;hb=0705951199dd03a594900f56aa58225d68314ba6;hp=7040f92adc51c014ed9dcf00aaa1ca13078b77c1;hpb=7febdcc0b99cb47ac2ac25eadf2651b9a68a45cc;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 7040f92..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;.
@@ -435,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
@@ -578,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:
@@ -668,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
@@ -709,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.
@@ -1027,8 +1047,8 @@ distribution.
These are the
If there is a chance that the software could do grave damage to a system,
@@ -1067,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
@@ -1130,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
@@ -1684,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
@@ -1835,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.
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).
@@ -4161,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
@@ -4175,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
@@ -4191,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
@@ -4202,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.
@@ -4286,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
@@ -4569,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.
@@ -4700,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
@@ -4708,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
@@ -5029,7 +5104,7 @@ a source or a binary package.