From a088baf8d9dafdd548f7549e449684b868312382 Mon Sep 17 00:00:00 2001 From: aba Date: Mon, 26 Dec 2005 11:13:33 +0000 Subject: [PATCH] spelling, gpg v4, homepage, sarge+etch, RoM severity, FSF address git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@3644 313b444b-1b9f-4f58-a734-7bb04f332e8d --- common.ent | 4 +- debian/changelog | 10 ++++- developers-reference.sgml | 95 ++++++++++++++++++++++++++------------- 3 files changed, 75 insertions(+), 34 deletions(-) diff --git a/common.ent b/common.ent index a397e19..6f19749 100644 --- a/common.ent +++ b/common.ent @@ -16,8 +16,8 @@ - + /usr/share/common-licenses/GPL"> diff --git a/debian/changelog b/debian/changelog index 16c07a7..da150cc 100644 --- a/debian/changelog +++ b/debian/changelog @@ -17,11 +17,17 @@ developers-reference (3.3.7) unstable; urgency=low - non-us discontinued. - document nmu changes wrt version tracking. Thanks, Justin Pryzby. Closes: #341197 - - fix spelling issues. - Closes: #336146 + - fix spelling issues. Thanks to various people. + Closes: #336146, #326857, #338660 - update menu policy helpers. Thanks, Florian Ernst. Closes: #340024 - send mia-mail to mia@qa. Thanks, Adam D. Barratt. Closes: #341568 - Joerg Jaspert is now freenode contact. Closes: #344303 + - give a clearer description of the gpg v4-key issues. Thanks, + Martin Michlmayr and Peter Palfrader. Closes: #317411 + - more verbose about Homepage. Closes: #339826 + - add sarge and etch. Closes: #327682 + - document severity of RoM-request bugs. Closes: #305947 + - update FSF address. Closes: #334820 -- Andreas Barth Sat, 25 Jun 2005 06:04:20 -0600 diff --git a/developers-reference.sgml b/developers-reference.sgml index 0dcd556..e83d7fe 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -7,7 +7,7 @@ %dynamicdata; - + @@ -165,7 +165,7 @@ Those who are seeking a sponsor can request one at . --> Please read the -inofficial debian-mentors FAQ at first. +unofficial debian-mentors FAQ at first.

If you wish to be a mentor and/or sponsor, more information is available in . @@ -232,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. gpg does this -automatically. +much less secure. +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). +

+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 pgpdump, +which will say something like "Public Key Packet - Ver 4". +

+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;. @@ -561,7 +588,7 @@ just zgrep for #debian-private in all the files.

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 @@ -1060,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 @@ -2087,9 +2116,9 @@ read . When bugs are closed by new uploads

-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. @@ -2458,7 +2487,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 @@ -2849,7 +2880,7 @@ $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 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.

@@ -2879,7 +2910,7 @@ In order to prevent autobuilders from needlessly trying to build your package, it must be included in packages-arch-specific, a list used by the wanna-build script. The current version is available as -; +; please see the top of the file for whom to contact for changes.

@@ -2889,7 +2920,7 @@ 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 +request their removal by filing a bug against ftp.debian.org @@ -2921,9 +2952,10 @@ Debian maintainer, talk to the upstream maintainer, or submit a bug. However, aesthetic changes must not be made in a non-maintainer upload.

-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. How to do a NMU @@ -2983,7 +3015,7 @@ managers. Please take additional care, and acknowledge that the usual way for a package to enter testing is through unstable.

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.

@@ -3543,7 +3575,7 @@ it's usually the file maintainers spend the most time on. Helper scripts

The rationale for using helper scripts in debian/rules 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 /usr/lib/menu (or /usr/lib/menu for executable binary menufiles, if this is needed), @@ -3616,7 +3648,7 @@ of the above, and provides a facility for creating new and updating old patches. See the package dbs for more information and hello-dbs for an example.

-dpatch also provides these facilities, but it's intented to be +dpatch also provides these facilities, but it's intended to be even easier to use. See the package dpatch for documentation and examples (in /usr/share/doc/dpatch). @@ -3817,7 +3849,10 @@ Note that we expect this field will eventually be replaced by a proper debian/control field understood by dpkg and &packages-host;. 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.

+until that is available. + Please make sure that this line matches the regular expression + /^ Homepage: [^ ]*$/, + as this allows packages.debian.org to parse it correctly.

@@ -4084,8 +4119,8 @@ Also, we document some best practices here.

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). Do not abuse debconf

@@ -4288,7 +4323,7 @@ usual blue one). Description: short and extended description

-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 @@ -4571,7 +4606,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.

@@ -4710,7 +4745,7 @@ The defining characteristic of a pristine source tarball is that the distributed by the upstream author. 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 currently distributing at any point in time. All that can be expected is that it is identical to @@ -5031,7 +5066,7 @@ a source or a binary package.

You may also be interested in contacting the persons who are subscribed to a given source package via . -You can do so by using the <package-name>@&pts-host; +You can do so by using the <package>@&pts-host; email address. @@ -5354,7 +5389,7 @@ list) before providing it for inclusion. It will save time for everyone, and avoid the chaos resulting in having several versions of the same document in bug reports.

-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. -- 2.30.2