X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=8698e292cf5c22047500915027370c8cfb5b9660;hb=44e618bcf365a9652306644907b9e167a39c13b7;hp=e5cec457ed170abee32fd4ccf90abe0ef14f0d3f;hpb=a4ae6572a8d9fde85d4ef6bb7f641bfae5bcf3cf;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index e5cec45..8698e29 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,32 +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. - -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 @@ -304,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. @@ -664,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

@@ -705,8 +703,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. @@ -964,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 @@ -987,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 @@ -1120,8 +1123,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 UploadQueue. @@ -1217,7 +1219,7 @@ $cfg{'delayed'} = { Once you've made that change, dupload can be used to easily upload a package in one of the delayed directories: -DELAY=5 dupload --to delayed <changes-file> +DELAY=5 dupload -X-to delayed <changes-file> --> @@ -1240,7 +1242,7 @@ 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;, and on +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 @@ -1501,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. @@ -1532,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

@@ -1786,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 @@ -1810,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 @@ -1877,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 @@ -1943,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 @@ -2064,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 @@ -2869,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) @@ -3090,7 +3111,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. @@ -3123,6 +3144,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'' @@ -3221,7 +3254,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. @@ -3494,195 +3529,6 @@ These are just some subjective hints, advice and pointers collected from Debian developers. Feel free to pick and choose whatever works best for you. - - 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. -

- - - Best practices for debian/rules

@@ -3776,7 +3622,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 @@ -4259,7 +4105,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 @@ -4273,10 +4119,10 @@ 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 +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 +Please use gettext-based templates. Install po-debconf on your development system and read its documentation ("man po-debconf" is a good start).

@@ -4289,10 +4135,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 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 -debian-i18n@lists.debian.org mailing list. +&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 @@ -4300,13 +4193,19 @@ 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 tempaltes +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 @@ -4791,6 +4690,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. +

+ + + + @@ -4851,7 +4942,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 @@ -4862,7 +4953,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.