X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=91442bc1c697acfdb8cec0c3504d5d45bacfe5aa;hb=46081ed86207d589fe557f4bacb4011f0eab1554;hp=4d4a87b75faa281d0ef999e7fa970dc27b8c4e23;hpb=e94546c373483de053d007056216645ef48117c9;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 4d4a87b..91442bc 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -2,16 +2,15 @@ %versiondata; - + %commondata; - + + - + revision of the original developer's reference in cvs-en-rev --> + FIXME: "> @@ -78,7 +77,7 @@ resources which can help maintainers with the quality of their packages ().

It should be clear that this reference does not discuss the technical -details of the Debian package nor how to generate Debian packages. +details of Debian packages nor how to generate them. Nor does this reference detail the standards to which Debian software must comply. All of such information can be found in the . @@ -126,7 +125,8 @@ with you on your package and upload it to the Debian archive once they are happy with the packaging work you have done. You can find a sponsor by mailing the &email-debian-mentors; mailing list, describing your package and yourself and asking for a sponsor (see -for more information on sponsoring). On the other hand, if you are +and for more information on sponsoring). +On the other hand, if you are interested in porting Debian to alternative architectures or kernels you can subscribe to port specific mailing lists and ask there how to get started. Finally, if you are interested in documentation or @@ -142,7 +142,7 @@ name="New Maintainer's Corner">. It describes exactly the preparations you have to do before you can register to become a Debian developer. -For example, before you apply, you have to to read the . Registering as a developer means that you agree with and pledge to uphold the Debian Social Contract; it is very important that @@ -221,7 +221,7 @@ To apply as a new maintainer, you need an existing Debian maintainer to verify your application (an advocate). After you have contributed to Debian for a while, and you want to apply to become a registered developer, an existing developer with whom you -have worked over the past months has to express his belief that you +have worked over the past months has to express their belief that you can contribute to Debian successfully.

When you have found an advocate, have your GnuPG key signed and have @@ -256,7 +256,8 @@ 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 . +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 . @@ -333,7 +334,7 @@ security update, etc.) occurs while you're on vacation. Sometimes it's nothing as critical as that, but it's still appropriate to let the others know that you're unavailable.

-In order to inform the other developers, there's two things that you should do. +In order to inform the other developers, there are two things that you should do. First send a mail to &email-debian-private; with "[VAC] " prepended to the subject of your messageThis is so that the message can be easily filtered by people who don't want to read vacation notices. @@ -357,7 +358,7 @@ they can be fixed in a future upstream release. While it's not your job to fix non-Debian specific bugs, you may freely do so if you're able. When you make such fixes, be sure to pass them on to the upstream maintainers as well. Debian users and developers will -sometimes submit patches to fix upstream bugs -- you should evaluate +sometimes submit patches to fix upstream bugs — you should evaluate and forward these patches upstream.

If you need to modify the upstream sources in order to build a policy @@ -371,7 +372,7 @@ need, always try not to fork from the upstream sources.

Generally you should deal with bug reports on your packages as described in . However, there's a special category of bugs that -you need to take care of -- the so-called release-critical bugs (RC bugs). +you need to take care of — the so-called release-critical bugs (RC bugs). All bug reports that have severity critical, grave or serious are considered to have an impact on whether the package can be released in the next stable release of Debian. @@ -590,17 +591,22 @@ administration (such as packages to be removed from the archive, suggestions for the web site, etc.), generally you'll report a bug against a ``pseudo-package''. See for information on how to submit bugs. +

+Some of the core servers are restricted, but the information from there +is mirror to another server. The bugs server

&bugs-host; is the canonical location for the Bug Tracking -System (BTS). If you plan on doing some statistical analysis or +System (BTS). +

+It is restricted; a mirror is available on merkel. +

+If you plan on doing some statistical analysis or processing of Debian bugs, this would be the place to do it. Please describe your plans on &email-debian-devel; before implementing anything, however, to reduce unnecessary duplication of effort or wasted processing time. -

-All Debian developers have accounts on &bugs-host;. The ftp-master server

@@ -608,6 +614,8 @@ The ftp-master.debian.org server holds the canonical copy of the Debian archive (excluding the non-US packages). Generally, package uploads go to this server; see .

+It is restricted; a mirror is available on merkel. +

Problems with the Debian FTP archive generally need to be reported as bugs against the ftp.debian.org pseudo-package or an email to &email-ftpmaster;, but also see the procedures in @@ -678,6 +686,20 @@ To request a CVS area, send a request via email to &email-debian-admin;. Include the name of the requested CVS area, the Debian account that should own the CVS root area, and why you need it. + chroots to different distributions +

+On some machines, there are chroots to different distributions available. +You can use them like + + +vore% dchroot unstable +Executing shell in chroot: /org/vore.debian.org/chroots/user/unstable + + +In all chroots, the normal user home directories are available. +You can find out which chroots are available via +&url-devel-machines;. + The Developers Database

@@ -715,7 +737,7 @@ Those features are documented at .

The &debian-formal; distribution consists of a lot of packages (.deb's, currently around &number-of-pkgs;) and a few -additional files (such documentation and installation disk images). +additional files (such as documentation and installation disk images).

Here is an example directory tree of a complete Debian archive:

@@ -740,13 +762,13 @@ In each of the areas, there is a directory for the source packages (source) and a directory for each supported architecture (binary-i386, binary-m68k, etc.).

-The main area contains additional directories which holds +The main area contains additional directories which hold the disk images and some essential pieces of documentation required for installing the Debian distribution on a specific architecture (disks-i386, disks-m68k, etc.). - Sections + Sections

The main section of the Debian archive is what makes up the official &debian-formal; distribution. The @@ -808,7 +830,7 @@ The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola Linux 2.2 kernel supports even more architectures, including ARM and UltraSPARC. Since Linux supports these platforms, Debian decided that it should, too. Therefore, Debian has ports underway; in fact, we -also have ports underway to non-Linux kernel. Aside from +also have ports underway to non-Linux kernels. Aside from i386 (our name for Intel x86), there is m68k, alpha, powerpc, sparc, hurd-i386, arm, ia64, hppa, s390, mips, @@ -822,7 +844,7 @@ ships for the i386, m68k, alpha, and support of five new architectures: ia64, hppa, s390, mips and mipsel.

-Information for developers or uses about the specific ports are +Information for developers and users about the specific ports are available at the . @@ -887,11 +909,12 @@ distribution changes from day-to-day. Since no special effort is done to make sure everything in this distribution is working properly, it is sometimes literally unstable.

- is generated automatically by taking +The "testing" distribution is generated +automatically by taking packages from unstable if they satisfy certain criteria. Those criteria should ensure a good quality for packages within testing. The update to testing is launched each day after the -new packages have been installed. +new packages have been installed. See .

After a period of development, once the release manager deems fit, the testing distribution is frozen, meaning that the policies @@ -957,7 +980,7 @@ in testing; The packages on which it depends must either be available in testing or they must be accepted into testing at the same time (and they will -if they respect themselves all the criteria); +if they respect all the necessary criteria);

To find out whether a package is progressing into testing or not, see the @@ -969,12 +992,12 @@ informed of the progression of their packages into testing.

The update_excuses file does not always give the precise reason why the package is refused, one may have to find it on their own by looking -what would break with the inclusion of the package. The gives some more information -about the usual problems which may be causing such troubles. +for what would break with the inclusion of the package. The + gives some more +information about the usual problems which may be causing such troubles.

Sometimes, some packages never enter testing because the set of -inter-relationship is too complicated and can not be sorted out +inter-relationship is too complicated and cannot be sorted out by the scripts. In that case, the release manager must be contacted, and he will force the inclusion of the packages.

@@ -1011,7 +1034,7 @@ into experimental. Whenever there is a new upstream version of a package that introduces new features but breaks a lot of old ones, it should either not be uploaded, or be uploaded to experimental. A new, beta, version of some software -which uses completely different configuration can go into +which uses a completely different configuration can go into experimental, at the maintainer's discretion. If you are working on an incompatible or complex upgrade situation, you can also use experimental as a staging area, so that testers can get early @@ -1030,7 +1053,10 @@ New software which isn't likely to damage your system can go directly into

An alternative to experimental is to use your personal web space on people.debian.org. - +

+Please consider to use the option -v to dpkg-buildpackage +if uploading a package to unstable to get the bugs finally closed that were +first fixed in experimental. Release code names

@@ -1074,8 +1100,8 @@ symbolic links for stable, testing, and

The various download archives and the web site have several mirrors available in order to relieve our canonical servers from heavy load. -In fact, some of the canonical servers aren't public, and instead a -first tier of mirrors balances the load. That way, users always access +In fact, some of the canonical servers aren't public — a first tier +of mirrors balances the load instead. That way, users always access the mirrors and get used to using them, which allows Debian to better spread its bandwidth requirements over several servers and networks, and basically makes users avoid hammering on one primary location. @@ -1097,15 +1123,16 @@ have accounts on these machines. The Incoming system

-The Incoming system is responsible of collecting updated packages and +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;.

Packages are uploaded by all the maintainers into a directory called unchecked. This directory is scanned every 15 minutes by -the katie script, which verifies the integrity of the uploaded packages and the cryptographic -signatures. If the package is considered ready to be installed, it +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 in the new directory, where it waits for an approval of the ftpmasters. If the package contains files to be installed @@ -1140,7 +1167,11 @@ or to move some files back in the unchecked directory. But all the other directories are only writable by the ftpmasters, that is why you can not remove an upload once it has been accepted. - Delayed incoming + Delayed incoming +

+Note: This description here is currently disabled, because +ftp-master is restricted. Please see for +the currently working way.

The unchecked directory has a special DELAYED subdirectory. It is itself subdivided in nine directories @@ -1192,8 +1223,8 @@ available in the various distributions. Each version links to a page which provides information, including the package description, the dependencies and package download links.

-The bug tracking system track bugs for each package. You can -view the bugs of a given package at the URL +The bug tracking system tracks bugs for each package. +You can view the bugs of a given package at the URL http://&bugs-host;/package-name. The madison utility @@ -1225,7 +1256,7 @@ the activity of a source package. This really means that you can get the same emails that the package maintainer gets, simply by subscribing to the package in the PTS.

-Each email sent through the PTS is classified and associated to one of +Each email sent through the PTS is classified under one of the keywords listed below. This will let you select the mails that you want to receive.

@@ -1338,7 +1369,7 @@ various commands to pts@qa.debian.org. keyword [<email>] {+|-|=} <list of keywords> - Accept (+) or refuse (-) mails associated to the given keyword(s). + Accept (+) or refuse (-) mails classified under the given keyword(s). Define the list (=) of accepted keywords. keyword <sourcepackage> [<email>] {+|-|=} <list of keywords> @@ -1420,7 +1451,7 @@ Usual news items may be used to announce that: something important will affect the package

-Both kind of news are generated in a similar manner: you just have to send +Both kinds of news are generated in a similar manner: you just have to send an email either to pts-static-news@qa.debian.org or to pts-news@qa.debian.org. The mail should indicate which package is concerned by having the name of the source package in a @@ -1573,7 +1604,7 @@ Changelog entries can be used to automatically close Debian bugs when the package is installed into the archive. See .

-It is conventional that the changelog entry notating of a package that +It is conventional that the changelog entry of a package that contains a new upstream version of the software looks like this: * new upstream version @@ -1676,11 +1707,8 @@ Actually, there are two other possible distributions: `stable-security' and `testing-security', but read for more information on those.

-It is technically possible to upload a package into several distributions -at the same time but it usually doesn't make sense to use that feature -because the dependencies of the package may vary with the distribution. -In particular, it never makes sense to combine the experimental -distribution with anything else (see ). +It is not possible to upload a package into several distributions +at the same time. Special case: uploads to the stable distribution @@ -1704,8 +1732,8 @@ appropriate proposed-updates archive when the advisory is released. See for detailed information on handling security problems.

-It is discouraged to change anything else in the package that isn't -important, because even trivial fixes can cause bugs later on. +Changing anything else in the package that isn't important is discouraged, +because even trivial fixes can cause bugs later on.

Packages uploaded to stable need to be compiled on systems running stable, so that their dependencies are limited to the libraries @@ -1721,6 +1749,10 @@ your package can be included in stable. Please be clear (and verbose, if necessary) in your changelog entries for uploads to stable, because otherwise the package won't be considered for inclusion. +

+It's best practice to speak with the stable release manager before +uploading to stable/stable-proposed-updates, so that the +uploaded package fits the needs of the next point release. Special case: uploads to testing-proposed-updates @@ -1746,25 +1778,17 @@ the authorization of the release manager before. Uploading to ftp-master

-To upload a package, you need a personal account on -&ftp-master-host;, which you should have as an -official maintainer. If you use scp or rsync -to transfer the files, place them into &us-upload-dir;; -if you use anonymous FTP to upload, place them into -&upload-queue;. -

-If you want to use feature described in , -you'll have to upload to ftp-master. It is the only upload -point that supports delayed incoming. +To upload a package, you should upload the files (including the signed +changes and dsc-file) with anonymous ftp to +&ftp-master-host; in the directory &upload-queue;. +To get the files processed there, they need to be signed with a key in the +debian keyring.

Please note that you should transfer 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. If you don't want to bother with transferring -the changes file last, you can simply copy your files to a temporary -directory on ftp-master and then move them to -&us-upload-dir;. -

+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 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 the overseas upload -queues on chiark or erlangen. If you are not sure +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 +when uploading packages. These handy programs help automate the process of uploading packages into Debian.

-After uploading your package, you can check how the archive -maintenance software will process it by running dinstall -on your changes file: -dinstall -n foo.changes -

-Note that dput can do this for you automatically. +For removing packages, please see the README file in that ftp directory, +and the Debian package . Uploading to non-US

-As discussed above, export controlled software should not be uploaded -to ftp-master. Instead, upload the package to -non-us.debian.org, placing the files in -&non-us-upload-dir; (again, both and can do this for you if invoked properly). By default, -you can use the same account/password that works on -ftp-master. If you use anonymous FTP to upload, place the -files into &upload-queue;. +Note: non-us is currently not processed any more.

-You can check your upload the same way it's done on ftp-master, -with: -dinstall -n foo.changes +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 @@ -1834,64 +1849,50 @@ advice. Again, it is strongly recommended that U.S. citizens and residents consult a lawyer before doing uploads to non-US. - Uploads via chiark -

-If you have a slow network connection to ftp-master, there are -alternatives. One is to upload files to Incoming via a -upload queue in Europe on chiark. For details connect to -. -

-Note: Do not upload packages containing software that is -export-controlled by the United States government to the queue on -chiark. Since this upload queue goes to ftp-master, the -prescription found in applies here as well. -

-The program dupload comes with support for uploading to -chiark; please refer to the documentation that comes with the -program for details. - - - Uploads via erlangen + Delayed uploads

-Another upload queue is available in Germany: just upload the files -via anonymous FTP to . +Delayed uploads are done for the moment via the delayed queue at +gluck. The upload-directory is +gluck:~tfheen/DELAYED/[012345678]-day. +0-day is uploaded approximately one hour before dinstall runs.

-The upload must be a complete Debian upload, as you would put it into -ftp-master's Incoming, i.e., a .changes files -along with the other files mentioned in the .changes. The -queue daemon also checks that the .changes is correctly -signed with GnuPG or OpenPGP by a Debian developer, so that no bogus files can find -their way to ftp-master via this queue. Please also make sure that -the Maintainer field in the .changes contains -your e-mail address. The address found there is used for all -replies, just as on ftp-master. -

-There's no need to move your files into a second directory after the -upload, as on chiark. And, in any case, you should get a -mail reply from the queue daemon explaining what happened to your -upload. Hopefully it should have been moved to ftp-master, but in -case of errors you're notified, too. +With a fairly recent dput, this section + +[tfheen_delayed] +method = scp +fqdn = gluck.debian.org +incoming = ~tfheen + +in ~/.dput.cf should work fine for uploading to the DELAYED queue.

-Note: Do not upload packages containing software that is -export-controlled by the United States government to the queue on -erlangen. Since this upload queue goes to ftp-master, the +Note: +Since this upload queue goes to ftp-master, the prescription found in applies here as well. -

-The program dupload comes with support for uploading to -erlangen; please refer to the documentation that comes with -the program for details. + Security uploads +

+Do NOT upload a package to the security upload queue (oldstable-security, +stable-security, etc.) without prior authorization from the security +team. If the package does not exactly meet the team's requirements, it +will cause many problems and delays in dealing with the unwanted upload. +For details, please see section . Other upload queues

-Another upload queue is available which is based in the US, and is a -good backup when there are problems reaching ftp-master. You can -upload files, just as in erlangen, to . +The scp queues on ftp-master, non-us and security are mostly unuseable +due to the login restrictions on those hosts.

-An upload queue is available in Japan: just upload the files via -anonymous FTP to . - +The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are +currently down. Work is underway to resurrect those. +

+The queues on master.debian.org, samosa.debian.org, master.debian.or.jp +and ftp.chiark.greenend.org.uk are down permanently and will not be +resurrected. The queue in Japan will be replaced with a new queue on +hp.debian.or.jp some day. +

+For the time being, the anonymous ftp queue on auric.debian.org (the +former ftp-master) works, but it is deprecated and will be removed at +some point in the future. Notification that a new package has been installed @@ -1918,7 +1919,7 @@ will receive a separate email notifying you of that. Read on below. Note also that if you upload via queues, the queue daemon software will also send you a notification by email. - Determining section and priority of a package + Specifying the package section, subsection and priority

The debian/control file's Section and Priority fields do not actually specify where the file will @@ -1947,9 +1948,11 @@ For more information about override files, see and .

-Note also that the term "section" is used for the separation of packages -according to their licensing, e.g. main, contrib and -non-free. This is described in another section, . +Note that the Section field describes both the section as +well as the subsection, which are described in . If the section is "main", it should be +omitted. The list of allowable subsections can be found in . Handling bugs @@ -2042,14 +2045,14 @@ Here's a list of steps that you may follow to handle a bug report: Decide whether the report corresponds to a real bug or not. Sometimes users are just calling a program in the wrong way because they haven't read the documentation. If you diagnose this, just close the bug with -enough information to let the user correct his problem (give pointers +enough information to let the user correct their problem (give pointers to the good documentation and so on). If the same report comes up again and again you may ask yourself if the documentation is good enough or if the program shouldn't detect its misuse in order to give an informative error message. This is an issue that may need to be brought to the upstream author.

-If the bug submitter disagree with your decision to close the bug, +If the bug submitter disagrees with your decision to close the bug, they may reopen it until you find an agreement on how to handle it. If you don't find any, you may want to tag the bug wontfix to let people know that the bug exists but that it won't be corrected. @@ -2060,10 +2063,10 @@ the BTS if you wish to keep it reported against your package). Before doing so, please read the . If the bug is real but it's caused by another package, just reassign -the bug the right package. If you don't know which package it should +the bug to the right package. If you don't know which package it should be reassigned to, you may either ask for help on &email-debian-devel; or reassign it to debian-policy to let them decide which -package is in fault. +package is at fault.

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 @@ -2071,8 +2074,8 @@ 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. -The bug submitter may have forgotten to provide some information, in that -case you have to ask him the information required. You may use the +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 reproduce the bug, you tag it unreproducible. Anyone who can reproduce the bug is then invited to provide more information @@ -2148,7 +2151,7 @@ changelog as described above. If you simply want to close bugs that don't have anything to do with an upload you made, do it by emailing an explanation to XXX-done@&bugs-host;. Do not close bugs in the changelog entry of a version if -the changes in that version of the package doesn't have any bearing on +the changes in that version of the package don't have any bearing on the bug.

For general information on how to write your changelog entries, see @@ -2170,8 +2173,10 @@ security advisories, and maintaining security.debian.org. When you become aware of a security-related bug in a Debian package, whether or not you are the maintainer, collect pertinent information about the problem, and promptly contact the security team at -&email-security-team; as soon as possible. Useful information -includes, for example: +&email-security-team; as soon as possible. DO NOT UPLOAD any +packages for stable; the security team will do that. + +Useful information includes, for example: What versions of the package are known to be affected by the @@ -2208,7 +2213,7 @@ There are a few ways a developer can learn of a security problem: he notices it on a public forum (mailing list, web site, etc.) someone files a bug report - someone informs him via private email + someone informs them via private email In the first two cases, the information is public and it is important @@ -2242,7 +2247,7 @@ itself is public, and can (and will) be examined by the general public.

There are two reasons for releasing information even though secrecy is -requested: the problem has been known for a while, or that the problem +requested: the problem has been known for a while, or the problem or exploit has become public. Security Advisories @@ -2315,21 +2320,32 @@ indeed succeeds on the unpatched package and fails on the fixed package. Test other, normal actions as well, as sometimes a security fix can break seemingly unrelated features in subtle ways.

+Do NOT include any changes in your package which are +not directly related to fixing the vulnerability. These will only +need to be reverted, and this wastes time. If there are other bugs in +your package that you would like to fix, make an upload to +proposed-updates in the usual way, after the security advisory is +issued. The security update mechanism is not a means for introducing +changes to your package which would otherwise be rejected from the +stable release, so please do not attempt to do this. +

Review and test your changes as much as possible. Check the differences from the previous version repeatedly (interdiff from the patchutils package and debdiff from devscripts are useful tools for this, see ).

-When packaging the fix, keep the following points in mind: +Be sure to verify the following items: - Make sure you target the right distribution in your + Target the right distribution in your debian/changelog. For stable this is stable-security and for testing this is testing-security, and for the previous stable release, this is oldstable-security. Do not target distribution-proposed-updates or stable! + The upload should have urgency=high. + Make descriptive, meaningful changelog entries. Others will rely on them to determine whether a particular bug was fixed. Always include an external reference, preferably a CVE @@ -2356,17 +2372,18 @@ When packaging the fix, keep the following points in mind: not build those. This point applies to normal package uploads as well. - If the upstream source has been uploaded to + Unless the upstream source has been uploaded to security.debian.org before (by a previous security update), build - the upload without the upstream source (dpkg-buildpackage - -sd). Otherwise, build with full source - (dpkg-buildpackage -sa). + the upload with full upstream source (dpkg-buildpackage + -sa). If there has been a previous upload to + security.debian.org with the same upstream version, you may upload + without upstream source (dpkg-buildpackage -sd). Be sure to use the exact same *.orig.tar.gz as used in the normal archive, otherwise it is not possible to move the security fix into the main archives later. - Be sure to build the package on a clean + Build the package on a clean system which only has packages installed from the distribution you are building for. If you do not have such a system yourself, you can use a debian.org machine (see ) @@ -2462,9 +2479,9 @@ avoid unwanted removals and to keep a trace of why a package has been removed. For example, you can provide the name of the package that supersedes the one to be removed.

-Usually you only ask the removal of a package maintained by yourself. +Usually you only ask for the removal of a package maintained by yourself. If you want to remove another package, you have to get the approval -of its last maintainer. +of its maintainer.

If in doubt concerning whether a package is disposable, email &email-debian-devel; asking for opinions. Also of interest is the @@ -2472,6 +2489,7 @@ If in doubt concerning whether a package is disposable, email package. When invoked as apt-cache showpkg package, the program will show details for package, including reverse depends. +Removal of orphaned packages is discussed on &email-debian-qa;.

Once the package has been removed, the package's bugs should be handled. They should either be reassigned to another package in the case where @@ -2484,7 +2502,7 @@ software is simply no more part of Debian. In the past, it was possible to remove packages from incoming. However, with the introduction of the new incoming system, this is no longer possible. Instead, you have to upload a new revision of your package with -a higher version as the package you want to replace. Both versions will be +a higher version than the package you want to replace. Both versions will be installed in the archive but only the higher version will actually be available in unstable since the previous version will immediately be replaced by the higher. However, if you do proper testing of your @@ -2492,8 +2510,8 @@ packages, the need to replace a package should not occur too often anyway. Replacing or renaming packages

-Sometimes you made a mistake naming the package and you need to rename -it. In this case, you need to follow a two-step process. First, set +When you make a mistake naming your package, you should follow a two-step +process to rename it. First, set your debian/control file to replace and conflict with the obsolete name of the package (see the for details). Once you've uploaded @@ -2522,20 +2540,20 @@ You should set the package maintainer to Debian QA Group against the pseudo package wnpp. The bug report should be titled O: package -- short description indicating that the package is now orphaned. The severity of the bug -should be set to normal. If you feel it's necessary, send a copy +should be set to normal; if the package has a priority of standard +or higher, it should be set to important. +If you feel it's necessary, send a copy to &email-debian-devel; by putting the address in the X-Debbugs-CC: header of the message (no, don't use CC:, because that way the message's subject won't indicate the bug number).

-If the package is especially crucial to Debian, you should instead submit +If you just intend to give the package away, but you can keep maintainership +for the moment, then you should instead submit a bug against wnpp and title it RFA: package -- -short description and set its severity to -important. RFA stands for Request For Adoption. -Definitely copy the message to debian-devel in this case, as described -above. +short description. +RFA stands for Request For Adoption.

-Read instructions on the -for more information. +More information is on the . Adopting a package

@@ -2578,7 +2596,7 @@ portability. Therefore, even if you are not a porter, you should read most of this chapter.

Porting is the act of building Debian packages for architectures that -is different from the original architecture of the package +are different from the original architecture of the package maintainer's binary package. It is a unique and essential activity. In fact, porters do most of the actual compiling of Debian packages. For instance, for a single i386 binary package, there must be @@ -2595,7 +2613,7 @@ the case. This section contains a checklist of ``gotchas'' often committed by Debian maintainers — common problems which often stymie porters, and make their jobs unnecessarily difficult.

-The first and most important watchword is to respond quickly to bug or +The first and most important thing is to respond quickly to bug or issues raised by porters. Please treat porters with courtesy, as if they were in fact co-maintainers of your package (which in a way, they are). Please be tolerant of succinct or even unclear bug reports, @@ -2644,7 +2662,7 @@ They should be removed by the `clean' target of Make sure you don't rely on locally installed or hacked configurations or programs. For instance, you should never be calling programs in /usr/local/bin or the like. Try not to rely on programs -be setup in a special way. Try building your package on another +being setup in a special way. Try building your package on another machine, even if it's the same architecture. Don't depend on the package you're building already being installed (a @@ -2757,7 +2775,7 @@ Porters may also have an unofficial location where they can put the results of their work during the waiting period. This helps others running the port have the benefit of the porter's work, even during the waiting period. Of course, such locations have no official -blessing or status, so buyer, beware. +blessing or status, so buyer beware. @@ -2831,7 +2849,7 @@ called a non-maintainer upload, or NMU. Debian porters, who compile packages for different architectures, occasionally do binary-only NMUs as part of their porting activity (see ). Another reason why NMUs are done is when a -Debian developers needs to fix another developers' packages in order to +Debian developer needs to fix another developer's packages in order to address serious security problems or crippling bugs, especially during the freeze, or when the package maintainer is unable to release a fix in a timely fashion. @@ -2912,12 +2930,12 @@ Make sure that the package's bugs that the NMU is meant to address are all filed in the Debian Bug Tracking System (BTS). If they are not, submit them immediately. -Wait a few days the response from the maintainer. If you don't get -any response, you may want to help him by sending the patch that fixes +Wait a few days for the response from the maintainer. If you don't get +any response, you may want to help them by sending the patch that fixes the bug. Don't forget to tag the bug with the "patch" keyword. Wait a few more days. If you still haven't got an answer from the -maintainer, send him a mail announcing your intent to NMU the package. +maintainer, send them a mail announcing your intent to NMU the package. Prepare an NMU as described in , test it carefully on your machine (cf. ). Double check that your patch doesn't have any unexpected side effects. @@ -2945,8 +2963,8 @@ and act later.

The following applies to porters insofar as they are playing the dual role of being both package bug-fixers and package porters. If a -porter has to change the Debian source archive, automatically their -upload is a source NMU and is subject to its rules. If a porter is +porter has to change the Debian source archive, their upload is +automatically a source NMU and is subject to its rules. If a porter is simply uploading a recompiled binary package, the rules are different; see .

@@ -3072,7 +3090,7 @@ In any case, you should not be upset by the NMU. An NMU is not a personal attack against the maintainer. It is a proof that someone cares enough about the package and that they were willing to help you in your work, so you should be thankful. You may also want to -ask them if they would be interested to help you on a more frequent +ask them if they would be interested in helping you on a more frequent basis as co-maintainer or backup maintainer (see ). @@ -3088,7 +3106,7 @@ packages in which a priority of Standard or which are part of the base set have co-maintainers.

Generally there is a primary maintainer and one or more -co-maintainers. The primary maintainer is the whose name is listed in +co-maintainers. The primary maintainer is the person whose name is listed in the Maintainer field of the debian/control file. Co-maintainers are all the other maintainers.

@@ -3202,7 +3220,7 @@ available at . Separating your patches into multiple files

Big, complex packages may have many bugs that you need to deal with. -If you correct a number of bug directly in the source, if you're not +If you correct a number of bugs directly in the source, and you're not careful, it can get hard to differentiate the various patches that you applied. It can get quite messy when you have to update the package to a new upstream version which integrates some of the fixes (but not @@ -3260,7 +3278,7 @@ this using an hand-crafted debian/rules file.

The following practices are relevant to the debian/control file. They supplement the .

The description of the package, as defined by the corresponding field @@ -3370,6 +3388,32 @@ spell-check it. ispell has a special -g option for debian/control files: ispell -d american -g debian/control +

+User usually expect these questions to be answered in the package +description. + + +What does the package do? If it is an add-on to another package, +then the short description of the package we are an add on to +should be put in here. + +Why should I want this package? This is related to the above, +but not the same (this is a mail user agent; this is cool, fast, +interfaces with pgp and ldap and imap, has features X, Y, and Z). + +If this package should not be installed directly, but is pulled in +by another package, this should be mentioned. + +If the package is experimental, or there are other reasons it +should not be used, if there are other packages that should be +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 (2. should talk about the class of packages, and +this about this particular package, if you have information related to both). + + @@ -3535,6 +3579,44 @@ changelog). Where's the description? If you can't think of a descriptive message, start by inserting the title of each different bug. + + + Suplimenting changelogs with NEWS.Debian files +

+Important news about changes in a package can also be put in NEWS.Debian +files. The news will be displayed by tools like apt-listchanges, before +all the rest of the changelogs. This is the preferred means to let the user +know about significant changes in a package. It is better than using +debconf notes since it is less annoying and the user can go back and refer +to the NEWS.Debian file after the install. And it's better than listing +major changes in README.Debian, since the user can easily miss such notes. +

+The file format is the same as a debian changelog file, but leave off +the asterisks and describe each news item with a full paragraph when +necessary rather than the more concise summaries that would go in a +changelog. It's a good idea to run your file through dpkg-parsechangelog to +check its formatting as it will not be automatically checked during build +as the changelog is. Here is an example of a real NEWS.Debian file: + +cron (3.0pl1-74) unstable; urgency=low + + The checksecurity script is no longer included with the cron package: + it now has its own package, "checksecurity". If you liked the + functionality provided with that script, please install the new + package. + + -- Steve Greenland <stevegr&debian.org> Sat, 6 Sep 2003 17:15:03 -0500 + +

+The NEWS.Debian file is installed as +/usr/share/doc/<package>/NEWS.Debian.gz. It is compressed, and +always has that name even in Debian native packages. If you use debhelper, +dh_installchangelogs will install debian/NEWS files for you. +

+Unlike changelog files, you need not update NEWS.Debian files with every +release. Only update them if you have something particularly newsworthy +that user should know about. If you have no news at all, there's no need +to ship a NEWS.Debian file in your package. No news is good news!