X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=77c70066508d1a6be0b34f5e78b8c4ab7cf00663;hb=37a98a9336288d6a1ce140b484fb2b3edbacc634;hp=5443f117b35f69b4be828115a00f97661d7c9a4c;hpb=6c9548b89ac55dd407becd75f0bdedfeb1f0e391;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 5443f11..77c7006 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -4,9 +4,10 @@ %versiondata; %commondata; + %dynamicdata; - + @@ -30,7 +31,7 @@ -copyright © 2004 Andreas Barth +copyright © 2004—2005 Andreas Barth copyright © 1998—2003 Adam Di Carlo @@ -53,6 +54,13 @@ the &debian-formal; distribution or on the World Wide Web at . You can also obtain it by writing to the &fsf-addr;. + +If you want to print this reference, you should use the . +This page is also available in . +]]> + Scope of This Document @@ -135,6 +143,32 @@ you can subscribe to port specific mailing lists and ask there how to 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. + + + Debian mentors and sponsors +

+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 for details). +

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

+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. + +Please read the +inofficial debian-mentors FAQ at first. +

+If you wish to be a mentor and/or sponsor, more information is +available in . Registering as a Debian developer @@ -162,8 +196,9 @@ Therefore, we need to verify new maintainers before we can give them accounts on our servers and let them upload packages.

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 @@ -175,12 +210,12 @@ has been signed by an existing Debian maintainer. If your GnuPG key is not signed yet, you should try to meet a Debian maintainer in person to get your key signed. There's a 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 - 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 +for more informations.)

If you do not have an OpenPGP key yet, generate one. Every developer @@ -197,12 +232,10 @@ You can use some other implementation of OpenPGP as well. Note that OpenPGP is an open standard based on .

- -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. gpg does this automatically.

@@ -216,8 +249,7 @@ Some countries restrict the use of cryptographic software by their 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 qua -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.

@@ -245,28 +277,6 @@ before actually applying. If you are well prepared, you can save a lot of time later on. - Debian mentors and sponsors -

-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 for details). -

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

-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. Those who are seeking a -sponsor can request one at . Please read the -inofficial debian-mentors FAQ at first. -

-If you wish to be a mentor and/or sponsor, more information is -available in . - - Debian Developer's Duties Maintaining your Debian information @@ -300,13 +310,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. @@ -364,6 +373,13 @@ The other thing to do is to mark yourself as "on vacation" in the Debian developers' LDAP database (this information is only accessible to Debian developers). Don't forget to remove the "on vacation" flag when you come back! +

+Ideally, you should sign up at the + +when booking a holiday and check if anyone there is looking for signing. +This is especially important when people go to exotic places +where we don't have any developers yet but +where there are people who are interested in applying. Coordination with upstream developers @@ -546,9 +562,7 @@ all the files.

There are other additional channels dedicated to specific subjects. #debian-bugs is used for coordinating bug squash parties. -#debian-boot is used to coordinate the work on the boot -floppies (i.e., the installer). - +#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 reading. Other channels are dedicated to an architecture or a set of @@ -564,6 +578,16 @@ French speaking people interested in Debian's development. Channels dedicated to Debian also exist on other IRC networks, notably on the IRC network. +

+To get a cloak on freenode, you send Göran Weinholt <weinholt@debian.org> +a signed mail where you tell what your nick is. +Put "cloak" somewhere in the Subject: header. +The nick should be registered: +. +The mail needs to be signed by a key in the Debian keyring. +Please see + +for more information about cloaks. Documentation @@ -645,17 +669,10 @@ an email to &email-ftpmaster;, but also see the procedures in The non-US server

-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 nonus.debian.org pseudo-package (notice -the lack of hyphen between "non" and "us" in the pseudo-package name -— that's for backwards compatibility). Remember to check whether or -not someone else has already reported the problem to the -. +The non-US server non-us.debian.org +was discontinued with the release of sarge. The pseudo-package +nonus.debian.org +stil exists for now. The www-master server

@@ -686,13 +703,12 @@ 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. The CVS server - +

Our CVS server is located on cvs.debian.org.

@@ -830,7 +846,7 @@ commercial distribution, for example.

On the other hand, a CD-ROM vendor could easily check the individual package licenses of the packages in non-free and include as -many on the CD-ROMs as he's allowed to. (Since this varies greatly from +many on the CD-ROMs as it's allowed to. (Since this varies greatly from vendor to vendor, this job can't be done by the Debian developers.)

Note that the term "section" is also used to refer to categories @@ -945,14 +961,17 @@ which control how packages move from unstable to testing are tightened. Packages which are too buggy are removed. No changes are allowed into testing except for bug fixes. After some time has elapsed, depending on progress, the testing 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 -testing distribution is renamed to stable, -overriding the old stable distribution, which is removed at -that time (although it can be found at &archive-host;). +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 testing is renamed to stable, +and a new copy is created for the new testing, +and the previous stable is renamed to oldstable +and stays there until it is finally archived. +On archiving, the contents are moved to &archive-host;).

This development cycle is based on the assumption that the unstable distribution becomes stable after passing a @@ -968,6 +987,9 @@ batch into the stable distribution and the revision level of the stable distribution is incremented (e.g., ‘3.0’ becomes ‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and so forth). +Please refer to +uploads to the stable distribution +for details.

Note that development under unstable continues during the freeze period, since the unstable distribution remains in @@ -1101,16 +1123,23 @@ 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 -unchecked. This directory is scanned every 15 minutes by +UploadQueue. +This directory is scanned every few minutes by a daemon called +queued, *.command-files are executed, and +remaining and correctly signed *.changes-files are moved +together with their corresponding files to the unchecked +directory. +This directory is not visible for most Developers, as ftp-master is restricted; +it is scanned every 15 minutes by the katie script, which verifies the integrity of the uploaded packages and their cryptographic signatures. If the package is considered ready to be installed, it is moved into the accepted directory. If this is the first upload of -the package, it is moved to the new directory, where it waits +the package (or it has new binary packages), +it is moved to the new directory, where it waits for approval by the ftpmasters. If the package contains files to be installed "by hand" it is moved to the byhand directory, where it waits for manual installation by the ftpmasters. Otherwise, if any error has been detected, @@ -1119,9 +1148,12 @@ the package is refused and is moved to the reject directory. Once the package is accepted, the system sends a confirmation mail to the maintainer and closes all the bugs marked as fixed by the upload, and the auto-builders may start recompiling it. The package is now publicly -accessible at (there is no -such URL for packages in the non-US archive) until it is really installed -in the Debian archive. This happens only once a day, the package +accessible at +until it is really installed +in the Debian archive. +This happens only once a day +(and is also called `dinstall run' for historical reasons); +the package is then removed from incoming and installed in the pool along with all the other packages. Once all the other updates (generating new Packages and Sources index files for example) have been @@ -1136,6 +1168,10 @@ If a package is released with Distribution: set to `unstable' or `experimental', the announcement will be posted to &email-debian-devel-changes; instead.

+Though ftp-master is restricted, a copy of the installation is available +to all developers on &ftp-master-mirror;. + Package information @@ -1206,7 +1242,8 @@ You can view the bugs of a given package at the URL The madison utility

madison is a command-line utility that is available -on both &ftp-master-host; and &non-us-host;. It +on &ftp-master-host;, and on +the mirror on &ftp-master-mirror;. It uses a single argument corresponding to a package name. In result it displays which version of the package is available for each architecture and distribution combination. An example will explain @@ -1466,7 +1503,7 @@ everything here:

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. @@ -1497,8 +1534,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 . + Goodies for Developers +

+ LWN Subscriptions +

+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 +. + + Managing Packages

@@ -1751,20 +1803,6 @@ the changes file last. Otherwise, your upload may be rejected because the archive maintenance software will parse the changes file and see that not all files have been uploaded.

- -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 -non-US/non-free (it's in non-free because of distribution issues -and not because of the license of the software). If you can't upload it to -ftp-master, then neither can you upload it to backup -queues that finally also end up on ftp-master. If you are not sure -whether U.S. patent controls or cryptographic controls apply to your -package, post a message to &email-debian-devel; and ask. -

You may also find the Debian packages or useful when uploading packages. These handy programs help automate the @@ -1775,41 +1813,7 @@ and the Debian package . Uploading to non-US

-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 non-us.debian.org, placing the files in -&upload-queue; (again, both and can do this for you if invoked properly). -

-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 . Maintainers of -non-US/non-free packages should further consult the of non-free software. -

-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. Delayed uploads @@ -1842,7 +1846,7 @@ For details, please see section . Other upload queues

-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 @@ -1908,7 +1912,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 and +name="dpkg-scanpackages" section="1"> and .

Note that the Section field describes both the section as @@ -2029,6 +2033,9 @@ If the bug is real but it's caused by another package, just reassign the bug to the right package. If you don't know which package it should be reassigned to, you should ask for help on IRC 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.

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 @@ -2036,6 +2043,17 @@ inflate the severity of bugs to make sure their bugs are fixed quickly. Some bugs may even be dropped to wishlist severity when the requested change is just cosmetic. +If the bug is real but the same problem has already been reported by +someone else, then the two relevant bug reports should be merged +into one using the merge command of the BTS. +In this way, when the +bug is fixed, all of the submitters will be informed of this. +(Note, however, that emails sent to one bug report's submitter won't +automatically be sent to the other report's submitter.) +For more +details on the technicalities of the merge command and its relative, +the unmerge command, see the BTS control server documentation. + The bug submitter may have forgotten to provide some information, in which case you have to ask them the required information. You may use the moreinfo tag to mark the bug as such. Moreover if you can't @@ -2100,6 +2118,17 @@ We prefer the closes: #XXX syntax, as it is the most concise entry and the easiest to integrate with the text of the changelog.

+If an upload is identified as Non-maintainer upload (NMU) +(and that is the case if the name of the person who commits this change +is not exactly the same as any one of Maintainer or Uploader, +except if the maintainer is the qa group), +than the bug is only tagged fixed instead of being closed. +If a maintainer upload is targetted to experimental, +than the tag fixed-in-experimental is added to the bug; +for NMUs, the tag fixed is used. +(The special rule for experimental is expected to change +as soon as version-tracking is added to the bug tracking system.) +

If you happen to mistype a bug number or forget a bug in the changelog entries, don't hesitate to undo any damage the error caused. To reopen wrongly closed bugs, send an reopen XXX command to @@ -2170,10 +2199,10 @@ case depends on the nature of the problem and corresponding fix, and whether it is already a matter of public knowledge.

-There are a few ways a developer can learn of a security problem: +There are a few ways developers can learn of a security problem: - he notices it on a public forum (mailing list, web site, etc.) + they notice it on a public forum (mailing list, web site, etc.) someone files a bug report someone informs them via private email @@ -2812,7 +2841,56 @@ different sub-flavors of Debian, which may or may not really be of general interest (for instance, a flavor of Debian built with gcc bounds checking). It will also enable Debian to recompile entire distributions quickly. - +

+The buildds admins of each arch can be contacted by the mail address +$arch@buildd.debian.org. + + When your package is not portable +

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

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

+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 +ftp.debian.org Non-Maintainer Uploads (NMUs) @@ -2824,8 +2902,9 @@ called a non-maintainer upload, or NMU. This section handles only source NMUs, i.e. NMUs which upload a new version of the package. For binary-only NMUs by porters or QA members, please see . -For buildd uploads (which are strictly speaking also NMUs), please see . +If a buildd builds and uploads a package, +that too is strictly speaking a binary NMU. +See for some more information.

The main reason why NMUs are done is when a developer needs to fix another developer's packages in order to @@ -3010,7 +3089,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. Building source NMUs @@ -3032,7 +3114,7 @@ to apply the patch that has been sent to you. Once this is done, you have to close the bugs that have been tagged fixed by the NMU. The easiest way is to use the -v option of dpkg-buildpackage, 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 closes: #nnnn in the changelog entry of your next upload. @@ -3065,6 +3147,18 @@ rather than doing an NMU, they should just submit worthwhile patches to the Bug Tracking System. Maintainers almost always appreciate quality patches and bug reports. + How dak detects NMUs +

+Whether an upload is treated as an NMU or as a maintainer upload by +the archive scripts and the bugtracking system (see ) is not decided by looking at the version +number (see ). Instead, an upload is handled as +an NMU if the maintainer address in the .changes file is not +binary the same as the address in the Maintainer field, or +any of the addresses the Uploaders field, of the dsc +file, and also if the maintainer address is not special (i.e. it is +not set to the QA Group address). + Terminology

There are two new terms used throughout this section: ``binary-only NMU'' @@ -3163,7 +3257,9 @@ Please see below for details. Updates from unstable

The scripts that update the testing 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 britney. +They generate the Packages files for the testing distribution, but they do so in an intelligent manner; they try to avoid any inconsistency and to use only non-buggy packages. @@ -3323,7 +3419,7 @@ interested in that, please peruse the code.)

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.) @@ -3349,9 +3445,8 @@ upload to testing-proposed-updates. Keep in mind that packages uploaded there are not automatically processed, they have to go through the hands of the release manager. So you'd better have a good reason to upload there. In order to know what a good reason is in the -release manager's eyes, you should read the instructions that he regularly -gives on &email-debian-devel-announce;. - +release managers' eyes, you should read the instructions that they regularly +give on &email-debian-devel-announce;.

You should not upload to testing-proposed-updates when you can update your packages through unstable. If you can't (for example because you have a @@ -3396,7 +3491,14 @@ All bugs of some higher severities are by default considered release-critical; c

Such bugs are presumed to have an impact on the chances that the package will be released with the stable release of Debian: in general, if a package has open release-critical bugs filed on it, it won't get into "testing", and consequently won't be released in "stable".

-The "testing" bug count for a package is considered to be roughly the bug count at the last point when the "testing" version equalled the "unstable" version. The bugs tagged woody or sarge will not be counted. Bugs with the sid tag will be counted, though. +The unstable bug count are all release-critical bugs +without either any release-tag (such as potato, woody) or with release-tag sid; +also, only if they are neither fixed nor set to sarge-ignore. +The "testing" bug count for a package is considered to be roughly +the bug count of unstable count at the last point +when the "testing" version equalled the "unstable" version. +

+This will change post-sarge, as soon as we have versions in the bug tracking system. @@ -3443,7 +3545,9 @@ it's usually the file maintainers spend the most time on. The rationale for using helper scripts in debian/rules is that lets 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, and add commands to the +put the file into /usr/lib/menu (or +/usr/lib/menu for executable binary menufiles, if this is needed), +and add commands to the maintainer scripts to register and unregister the menu entries. Since this is a very common thing for packages to do, why should each maintainer rewrite all this on their own, sometimes with bugs? Also, @@ -3523,7 +3627,7 @@ A single source package will often build several binary packages, either to provide several flavors of the same software (e.g., the vim source package) or to make several small packages instead of a big one (e.g., if the user can install only the -subset she needs, and thus save some disk space). +subset needed, and thus save some disk space).

The second case can be easily managed in debian/rules. You just need to move the appropriate files from the build directory @@ -3681,8 +3785,11 @@ used instead, it should be here as well. How is this package different from the competition? Is it a better implementation? more features? different features? Why should I -choose this package (the second questions is about the class of packages, and +choose this package. + @@ -3973,6 +4080,385 @@ future. Debconf is a great tool but it is often poorly used. Many common mistakes are listed in the man page. It is something that you must read if you decide to use debconf. +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). + + Do not abuse debconf +

+Since debconf appeared in Debian, it has been widely abused and +several criticisms received by the Debian distribution come from +debconf abuse with the need of answering a wide bunch of questions +before getting any little thing installed. +

+Keep usage notes to what they belong: the NEWS.Debian, or +README.Debian file. Only use notes for important notes which may +directly affect the package usability. Remember that notes will always +block the install until confirmed or bother the user by email. +

+Carefully choose the questions priorities in maintainer scripts. See + for details about priorities. +Most questions should use medium and low priorities. + + General recommendations for authors and translators +

+ Write correct English +

+Most Debian package maintainers are not native English speakers. So, +writing properly phrased templates may not be easy for them. +

+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 +work...or even of Debian itself. +

+Avoid technical jargon as much as possible. If some terms sound common +to you, they may be impossible to understand for others. If you cannot +avoid them, try to explain them (use the extended description). When +doing so, try to balance between verbosity and simplicity. + + Be kind to translators +

+Debconf templates may be translated. Debconf, along with its sister +package po-debconf offers a simple framework for getting +templates translated by translation teams or even individuals. +

+Please use gettext-based templates. Install po-debconf on your +development system and read its documentation ("man po-debconf" is a +good start). +

+Avoid changing templates too often. Changing templates text induces +more work to translators which will get their translation "fuzzied". If +you plan changes to your original templates, please contact +translators. Most active translators are very reactive and getting +their work included along with your modified templates will save you +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 podebconf-report-po from the +po-debconf package is highly recommended to warn translators which +have incomplete translations and request them for updates. +

+If in doubt, you may also contact the translation team for a given +language (debian-l10n-xxxxx@lists.debian.org), or the +&email-debian-i18n; mailing list. +

+Calls for translations posted to +&email-debian-i18n; with the debian/po/templates.pot file +attached or referenced in a URL are encouraged. Be sure to mentions in +these calls for new translations which languages you have existing +translations for, in order to avoid duplicate work. + Unfuzzy complete translations when correcting typos and spelling +

+ +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: + + +Put all incomplete PO files out of the way. You can check the +completeness by using (needs the gettext package installed): +for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null +--statistics $i; done + +move all files which report either fuzzy strings to a temporary +place. Files which report no fuzzy strings (only translated and +untranslated) will be kept in place. + +now and now only, modify the template for the typos +and check again that translation are not impacted (typos, spelling +errors, sometimes typographical corrections are usually OK) + +run debconf-updatepo. This will fuzzy all strings +you modified in translations. You can see this by running the above +again + +use the following command: +for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done + +move back to debian/po the files which showed fuzzy strings in the first step + +run debconf-updatepo again + + Do not make assumptions about interfaces +

+Templates text should not make reference to widgets belonging to some +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. + + Do not use first person +

+You should avoid the use of first person ("I will do this..." or "We +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 +would write a scientific paper. + + Be gender neutral +

+The world is made of men and women. Please use gender-neutral +constructions in your writing. This is not Political Correctness, this +is showing respect to all humanity. + + + Templates fields definition +

+This part gives some information which is mostly taken from the + manual page. + + Type +

+ + string: +

+Results in a free-form input field that the user can type any string into. + + password: +

+Prompts the user for a password. Use this with caution; be aware that +the password the user enters will be written to debconf's +database. You should probably clean that value out of the database as +soon as is possible. + + boolean: +

+A true/false choice. Remember: true/false, NOT YES/NO... + + select: +

+A choice between one of a number of values. The choices must be +specified in a field named 'Choices'. Separate the possible values +with commas and spaces, like this: Choices: yes, no, maybe + + multiselect: +

+Like the select data type, except the user can choose any number of + + items from the choices list (or chose none of them). + + note: +

+Rather than being a question per se, this datatype indicates a note +that can be displayed to the user. It should be used only for +important notes that the user really should see, since debconf will go +to great pains to make sure the user sees it; halting the install for +them to press a key, and even mailing the note to them in some +cases. + + text: +

+This type is now considered obsolete: don't use it. + + error: +

+THIS TEMPLATE TYPE IS NOT HANDLED BY DEBCONF YET. +

+It has been added to cdebconf, the C version of debconf, first used in +the Debian Installer. +

+Please do not use it unless debconf supports it. +

+This type is designed to handle error message. It is mostly similar to +the "note" type. Frontends may present it differently (for instance, +the dialog frontend of cdebconf draws a red screen instead of the +usual blue one). + + + Description: short and extended description +

+Templates 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 +that it may be accomodated by most debconf interfaces. Keeping it +short also helps translators, as usually translations tend to end up +being longer than the original. +

+The short description should be able to stand on its own. Some +interfaces do not show the long description by default, or only if the +user explicitely asks for it or even do not show it at all. Avoid +things like "What do you want to do?" +

+The short description does not necessarily have to be a full +sentence. This is part of the "keep it short and efficient" +recommendation. +

+The extended description should not repeat the short description word +for word. If you can't think up a long description, then first, think +some more. Post to debian-devel. Ask for help. Take a writing class! +That extended description is important. If after all that you still +can't come up with anything, leave it blank. +

+The extended description should use complete sentences. Paragraphs +should be kept short for improved readability. Do not mix two ideas +in the same paragraph but rather use another paragraph. +

+Don't be too verbose. Some debconf interfaces cannot deal very well +with descriptions of more than about 20 lines, so try to keep it below +this limit. +

+For specific rules depending on templates type (string, boolean, +etc.), please read below. + + Choices +

+This field should be used for Select and Multiselect types. It +contains the possible choices which will be presented to users. These +choices should be separated by commas. + + + Default +

+This field is optional. It contains the default answer for string, +select and multiselect templates. For multiselect templates, it may +contain a comma-separated list of choices. + + Templates fields specific style guide +

+ + Type field +

+No specific indication except: use the appropriate type by referring +to the previous section. + + Description field +

+Below are specific instructions for properly writing the Description +(short and extended) depending on the template type. + + String/password templates +

+ + The short description is a prompt and NOT a title. Avoid + question style prompts ("IP Address?") in favour of + "opened" prompts ("IP address:"). + The use of colons is recommended. + + The extended description is a complement to the short description. + In the extended part, explain what is being asked, rather than ask + the same question again using longer words. Use complete sentences. + Terse writing style is strongly discouraged. + + + Boolean templates +

+ + The short description should be phrased in the form of a question + which should be kept short and should generally end with a question + mark. Terse writing style is permitted and even encouraged if the + question is rather long (remember that translations are often longer + than original versions) + + The extended description should NOT include a question. + + Again, please avoid referring to specific interface widgets. A common + mistake for such templates is "if you answer Yes"-type + constructions. + + + Select/Multiselect +

+ + The short description is a prompt and NOT a title. Do NOT use useless + "Please choose..." constructions. Users are clever enough to figure + out they have to choose something...:) + + The extended description will complete the short description. It may + refer to the available choices. It may also mention that the user + may choose more than one of the available choices, if the template + is a multiselect one (although the interface often makes this + clear). + + + Notes +

+ + The short description should be considered to be a *title*. + + The extended description is what will be displayed as a more detailed + explanation of the note. Phrases, no terse writing style. + + DO NOT ABUSE DEBCONF. Notes are the most common way to abuse + debconf. As written in debconf-devel manual page: it's best to use them + only for warning about very serious problems. The NEWS.Debian or + README.Debian files are the appropriate location for a lot of notes. + If, by reading this, you consider converting your Note type templates + to entries in NEWS/Debian or README.Debian, plus consider keeping existing + translations for the future. + + + + Choices field +

+If the Choices are likely to change often, please consider using the +"__Choices" trick. This will split each individual choice into a +single string, which will considerably help translators for doing +their work. + + Default field +

+If the default value, for a "select" template, is likely to vary +depending on the user language (for instance, if the choice is a +language choice), please use the "_DefaultChoice" trick. +

+This special field allow translators to put the most appropriate +choice according to their own language. It will become the default +choice when their language is used while your own mentioned Default +Choice will be used chan using English. +

+Example, taken from the geneweb package templates: + +Template: geneweb/lang +Type: select +__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv) +# This is the default choice. Translators may put their own language here +# instead of the default. +# WARNING : you MUST use the ENGLISH FORM of your language +# For instance, the french translator will need to put "French (fr)" here. +_DefaultChoice: English (en)[ translators, please see comment in PO files] +_Description: Geneweb default language: + +

+Note the use of brackets which allow internal comments in debconf +fields. Also note the use of comments which will show up in files the +translators will work with. +

+The comments are needed as the DefaultChoice trick is a bit +confusing: the translators may put their own choice + + Default field +

+Do NOT use empty default field. If you don't want to use default +values, do not use Default at all. +

+If you use po-debconf (and you SHOULD, see 2.2), consider making this +field translatable, if you think it may be translated. +

+If the default value may vary depending on language/country (for +instance the default value for a language choice), consider using the +special "_DefaultChoice" type documented in ). @@ -4209,6 +4695,198 @@ to your short description. If you are looking for examples, just run: apt-cache search .|grep transitional. + + + Best practices for orig.tar.gz files +

+ There are two kinds of original source tarballs: Pristine source + and repackaged upstream source. +

+ + Pristine source +

+The defining characteristic of a pristine source tarball is that the +.orig.tar.gz file is byte-for-byte identical to a tarball officially +distributed by the upstream author. + +We cannot prevent upstream authors from changing the tarball +they distribute without also upping 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 +something that upstream once did distribute. + +If a difference arises later (say, if upstream notices that he wasn't +using maximal comression in his original distribution and then +re-gzips it), that's just too bad. Since there is no good way +to upload a new .orig.tar.gz for the same version, there is not even +any point in treating this situation as a bug. + +This makes it possible to use checksums to easily verify that all +changes between Debian's version and upstream's are contained in the +Debian diff. Also, if the original source is huge, upstream authors +and others who already have the upstream tarball can save download +time if they want to inspect your packaging in detail. +

+

+There is no universally accepted guidelines that upstream authors +follow regarding to the directory structure inside their tarball, but +dpkg-source is nevertheless able to deal with most +upstream tarballs as pristine source. Its strategy is equivalent to +the following: +

+

+ + +It unpacks the tarball in an empty temporary directory by doing + + +zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - + + + +If, after this, the temporary directory contains nothing but one +directory and no other files, dpkg-source renames that +directory to +<packagename>-<upstream-version>(.orig). The name +of the top-level directory in the tarball does not matter, and is +forgotten. + + +Otherwise, the upstream tarball must have been packaged without a +common top-level directory (shame on the upstream author!). In this +case, dpkg-source renames the temporary directory +itself to +<packagename>-<upstream-version>(.orig). + + +

+ + + Repackaged upstream source +

+You should upload packages with a pristine source +tarball if possible, but there are various reasons why it might not be +possible. This is the case if upstream does not distribute the source +as gzipped tar at all, or if upstream's tarball contains non-DFSG-free +material that you must remove before uploading. +

+

+In these cases the developer must construct a suitable .orig.tar.gz +file himself. We refer to such a tarball as a "repackaged upstream +source". Note that a "repackaged upstream source" is different from a +Debian-native package. A repackaged source still comes with +Debian-specific changes in a separate .diff.gz and still has +a version number composed of <upstream-version> and +<debian-revision>. +

+

+There may be cases where it is desirable to repackage the source even +though upstream distributes a .tar.gz that could in principle +be used in its pristine form. The most obvious is if +significant space savings can be achieved by recompressing +the tar archive or by removing genuinely useless cruft from the +upstream archive. Use your own discretion here, but be prepared to +defend your decision if you repackage source that could have been +pristine. +

+

+A repackaged .orig.tar.gz +

+

+ + +

+must contain detailed information how +the repackaged source was obtained, and how this can be reproduced, in +README.Debian-source or a similar file. This file should +be in the diff.gz part of the Debian source package, +usually in the debian directory, not in the +repackaged orig.tar.gz. It is also a good idea to provide a +get-orig-source target in your debian/rules file +that repeats the process, as described in the Policy Manual, . +

+ + +should not contain any file that does not come from the +upstream author(s), or whose contents has been changed by you. + +As a special exception, if the omission of non-free files would lead +to the source failing to build without assistance from the Debian +diff, it might be appropriate to instead edit the files, omitting only +the non-free parts of them, and/or explain the situation in a +README.Debian-source file in the root of the source +tree. But in that case please also urge the upstream author to make +the non-free components easier seperable from the rest of the source. + + + +

+should, except where impossible for legal reasons, +preserve the entire building and portablility infrastructure provided +by the upstream author. For example, it is not a sufficient reason for +omitting a file that it is used only when building on +MS-DOS. Similarly, a Makefile provided by upstream should not be +omitted even if the first thing your debian/rules does is +to overwrite it by running a configure script. +

+

+(Rationale: It is common for Debian users who need to build +software for non-Debian platforms to fetch the source from a Debian +mirror rather than trying to locate a canonical upstream distribution +point). +

 + +should use +<packagename>-<upstream-version>.orig as the name +of the top-level directory in its tarball. This makes it possible to +distinguish pristine tarballs from repackaged ones. + + +should be gzipped with maximal compression. + + +

+

+The canonical way to meet the latter two points is to let +dpkg-source -b construct the repackaged tarball from an +unpacked directory. +

+ + + Changing binary files in diff.gz +

+Sometimes it is necessary to change binary files contained in the +original tarball, or to add binary files that are not in it. +If this is done by simply copying the files into the debianized source +tree, dpkg-source will not be able to handle this. On the +other hand, according to the guidelines given above, you cannot +include such a changed binary file in a repackaged +orig.tar.gz. Instead, include the file in the +debian directory in uuencoded (or similar) +form + +The file should have a name that makes it clear which binary file it +encodes. Usually, some postfix indicating the encoding should be +appended to the original filename. +. +The file would then be decoded and copied to its place during the +build process. Thus the change will be visible quite easy. +

+

+Some packages use dbs to manage patches to their upstream +source, and always create a new orig.tar.gz file that +contains the real orig.tar.gz in its toplevel directory. This +is questionable with respect to the preference for pristine source. On +the other hand, it is easy to modify or add binary files in this case: +Just put them into the newly created orig.tar.gz file, +besides the real one, and copy them to the right place during the +build process. +

+ + + + @@ -4269,7 +4947,7 @@ close those that you can't reproduce anymore. To find out all the bugs you submitted, you just have to visit http://&bugs-host;/from:<your-email-addr>. - Reporting lots of bugs at once + Reporting lots of bugs at once (mass bug filing)

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 @@ -4280,7 +4958,8 @@ is emitted.

If you report more than 10 bugs on the same topic at once, it is recommended that you send a message to &email-debian-devel; describing -your intention before submitting the report. This will allow other +your intention before submitting the report, and mentioning the +fact in the subject of your mail. This will allow other developers to verify that the bug is a real problem. In addition, it will help prevent a situation in which several maintainers start filing the same bug report simultaneously. @@ -4418,7 +5097,7 @@ happened to the person they sponsored. It is also allowed to post a query to &email-debian-devel;, asking if anyone is aware of the whereabouts of the missing maintainer.

-Once you have gathered all of this, you can contact &email-debian-qa;. +Once you have gathered all of this, you can contact &email-mia;. People on this alias will use the information you provided in order to decide how to proceed. For example, they might orphan one or all of the packages of the maintainer. If a packages has been NMUed, they might prefer @@ -4454,9 +5133,11 @@ Sponsoring a package means uploading a package for a maintainer who is not able to do it on their own, a new maintainer applicant. Sponsoring a package also means accepting responsibility for it.

+ New maintainers usually have certain difficulties creating Debian packages — this is quite understandable. That is why the sponsor is there, to check the package and verify that it is good enough for inclusion in Debian.