X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=9ae4e099e44cf431b1035b2268f86b0297388c4b;hp=9c4f76eb80a81a515cdf03198d765f35183937dc;hb=24cbe1bfd9e63ce3a247fca05f94282f1e69effc;hpb=ace72fb856eb4d3f366de9abcb1c60840081b2f5 diff --git a/developers-reference.sgml b/developers-reference.sgml index 9c4f76e..9ae4e09 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - +

The procedures discussed within include how to become a maintainer -(); how to upload new packages (); how and when to do ports and interim releases of other -maintainers' packages (); how to move, remove, or orphan -packages (); and how to handle bug reports -(). +(); how to create new packages +() and how to upload packages (); +how to handle bug reports (); how to move, +remove, or orphan packages (); how to port +packages (); and how and when to do interim +releases of other maintainers' packages ().

The resources discussed in this reference include the mailing lists () and servers (); a @@ -479,13 +480,14 @@ for Debian related correspondence such as contacting upstream authors about licenses, bugs, etc. or discussing the project with others where it might be useful to have the discussion archived somewhere. + IRC channels

Several IRC channels are dedicated to Debian's development. They are mainly hosted on the network (previously known as Open Projects Network). The irc.debian.org DNS entry is an alias to -irc.openprojects.net. +irc.freenode.net.

The main channel for Debian in general is #debian. This is a large, general-purpose channel where users can find recent news in the topic and @@ -523,6 +525,10 @@ package) ... Some non-English developers' channels exist as well, for example #debian-devel-fr for French speaking people interested in Debian's development. +

+Channels dedicated to Debian also exist on other IRC networks, notably on +the IRC network. Documentation @@ -664,16 +670,20 @@ the Debian account that should own the CVS root area, and why you need it.

The Developers Database, at , is an LDAP directory for managing Debian developer attributes. You can use this -resource to search the list of Debian developers. For information on -keeping your entry the developer database up-to-date, see . Part of this information is also available through +resource to search the list of Debian developers. +Part of this information is also available through the finger service on Debian servers, try finger yourlogin@db.debian.org to see what it reports.

-This database lets you register some other information like public SSH -keys that will be automatically installed on the official debian machines -or like *.debian.net DNS entry. Those features are documented -at . +Developers can +to change their debian-private list subscription, their personal +information, to mark themselves on vacation, etc. +For more information on keeping your entry the developer database +up-to-date, please see . +

+One can also submit their SSH keys to be used for authorization on the +official Debian machines, and even add new *.debian.net DNS entries. +Those features are documented at . The Debian archive @@ -752,6 +762,13 @@ 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 vendor to vendor, this job can't be done by the Debian developers.) +

+Note also that the term "section" is also used to refer to categories +which simplify the organization and browsing of available packages, e.g. +admin, net, utils etc. Once upon a time, these +sections (subsections, rather) existed in the form of subdirectories within +the Debian archive. Nowadays, these exist only in the "Section" header +fields of packages. Architectures @@ -785,20 +802,6 @@ available at the . - Packages

@@ -1034,7 +1037,15 @@ the other packages. Once all the other updates (generating new made, a special script is called to ask all the primary mirrors to update themselves.

-All debian developers have write access to the unchecked +The archive maintenance software will also send the OpenPGP/GnuPG signed +.changes file that you uploaded to the appropriate mailing +lists. If a package is released with the Distribution: set to +`stable', the announcement is sent to &email-debian-changes;. +If a package is released with Distribution: set to `unstable' +or `experimental', the announcement will be posted to +&email-debian-devel-changes; instead. +

+All Debian developers have write access to the unchecked directory in order to upload their packages, they also have that access to the reject directory in order to remove their bad uploads or to move some files back in the unchecked directory. But @@ -1042,7 +1053,7 @@ 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 -

+

The unchecked directory has a special DELAYED subdirectory. It is itself subdivided in nine directories called 1-day to 9-day. Packages which are uploaded in @@ -1079,6 +1090,7 @@ 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> + The "testing" distribution

@@ -1111,24 +1123,28 @@ or they must be accepted into testing at the same time (and they will if they respect themselves all the criteria);

-The scripts are generating some output files to explain why some packages -are kept out of testing. They are available at . Alternatively, it is possible to use -the grep-excuses program which is in the -devscripts package. It can be easily put in a - -to keep someone informed of the progression of his packages in testing. +To find out whether a package is progressing into testing or not, see the +testing script output on the , or use the program grep-excuses +which is in the devscripts package. This utility can +easily be used in a to keep one +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 +id="&url-testing-maint;" name="testing web page"> 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 by the scripts. In that case, the release manager must be contacted, and he will force the inclusion of the packages. +

+In general, please refer to the for more information. It also includes +answers to some of the frequently asked questions. + Package information

@@ -1222,6 +1238,11 @@ architectures). CVS commits if the maintainer has setup a system to forward commit notification to the PTS. + + ddtp + +Translations of descriptions or debconf templates +submitted to the Debian Description Translation Project. The PTS email interface @@ -1262,6 +1283,7 @@ various commands to pts@qa.debian.org. control@bugs.debian.org summary: automatic summary mails about the state of a package cvs: notification of CVS commits + ddtp: translations of descriptions and debconf templates upload-source: announce of a new source upload that has been accepted upload-binary: announce of a new binary-only upload (porting) @@ -1341,9 +1363,8 @@ packages are under your responsibility. This chapter contains information related to creating, uploading, maintaining, and porting packages. - Package uploads - New packages + New packages

If you want to create a new package for the Debian distribution, you should first check the - Adding an entry to debian/changelog + + Recording changes in the package

Changes that you make to the package need to be recorded in the debian/changelog. These changes should provide a concise @@ -1428,6 +1449,13 @@ There are tools to help you create entries and finalize the and . + Package uploads + +

+When a package is uploaded to the Debian archive, it must be accompanied by +a .changes control file, which gives directions to the archive +maintenance software for its handling. This is generated by +dpkg-genchanges during the normal package build process. Checking the package prior to upload

@@ -1460,25 +1488,27 @@ Remove the package, then reinstall it. - Generating the changes file + Layout of the source files

-When a package is uploaded to the Debian FTP archive, it must be -accompanied by a .changes file, which gives directions to the -archive maintainers for its handling. This is usually generated by -dpkg-genchanges during the normal package build process. -

-The changes file is a control file with the following fields: +There are two types of Debian source packages: + + the so-called native packages, where there is no + distinction between the original sources and the patches + applied for Debian + the (more common) packages where there's an original source + tarball file accompanied by another file that contains the + patches applied for Debian +

-&control-file-fields; +For the native packages, the source package includes a Debian source control +file (.dsc) and the source tarball (.tar.gz). A source +package of a non-native package includes a Debian source control file, the +original source tarball (.orig.tar.gz) and the Debian patches +(.diff.gz).

-All of these fields are mandatory for a Debian upload. See the list -of control fields in the for the contents of these fields. You can close bugs -automatically using the Description field, see . - - - The original source tarball +Whether a package is native or not is determined when it is built by +. The rest of this section +relates only to non-native packages.

The first time a version is uploaded which corresponds to a particular upstream version, the original source tar file should be uploaded and @@ -1499,17 +1529,20 @@ source tar-file used by dpkg-source when constructing the byte-for-byte identical with the one already in the archive. - Picking a distribution + Picking a distribution

-The Distribution field, which originates from the first line of -the debian/changelog file, indicates which distribution the -package is intended for. +Each upload needs to specify which distribution the package is intended +for. The package build process extracts this information from the first +line of the debian/changelog file and places it in the +Distribution field of the .changes file.

There are several possible values for this field: `stable', `unstable', -`testing-proposed-updates' and `experimental'. Normally, packages are uploaded into -unstable. Actually, there are two other possible distributions: -`stable-security' and `testing-security'. However they are used by the -security team; do not upload there without their agreement. +`testing-proposed-updates' and `experimental'. Normally, packages are +uploaded into unstable. +

+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 @@ -1517,8 +1550,7 @@ 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. - - Uploading to stable + Uploading to stable

Uploading to stable means that the package will be placed into the stable-proposed-updates directory of the Debian archive for further @@ -1554,7 +1586,7 @@ verbose, if necessary) in your changelog entries for uploads to stable, because otherwise the package won't be considered for inclusion. - Uploading to testing-proposed-updates + Uploading to testing-proposed-updates

The testing distribution is fed with packages from unstable according to the rules explained in . However, the release manager may stop the testing @@ -1572,6 +1604,7 @@ packages through unstable. If you can't (for example because you have a newer development version in unstable), you may use it but it is recommended to ask the authorization of the release manager before. + Uploading a package Uploading to ftp-master @@ -1715,26 +1748,6 @@ An upload queue is available in Japan: just upload the files via anonymous FTP to . - - Announcing package uploads -

-When a package is uploaded, an announcement should be posted to one of -the ``debian-changes'' lists. This is now done automatically by the archive -maintenance software when it runs (usually once a day). You just need to use -a recent dpkg-dev (>= 1.4.1.2). The mail generated by -the archive maintenance software will contain the OpenPGP/GnuPG signed -.changes files that you uploaded with your package. -Previously, dupload used to send those announcements, so -please make sure that you configured your dupload not to -send those announcements (check its documentation and look for -``dinstall_runs''). -

-If a package is released with the Distribution: set to -`stable', the announcement is sent to &email-debian-changes;. If a -package is released with Distribution: set to `unstable', -or `experimental', the announcement will be -posted to &email-debian-devel-changes; instead. - Notification that a new package has been installed

@@ -1757,7 +1770,7 @@ The installation notification also includes information on what section the package was inserted into. If there is a disparity, you will receive a separate email notifying you of that. Read on below. - The override file + Determining section and priority of a package

The debian/control file's Section and Priority fields do not actually specify where the file will @@ -1783,558 +1796,427 @@ 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 , &file-bts-mailing;, and -&file-bts-info;. - - - - Non-Maintainer Uploads (NMUs) -

-Under certain circumstances it is necessary for someone other than the -official package maintainer to make a release of a package. This is -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 -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. -

-This chapter contains information providing guidelines for when and -how NMUs should be done. A fundamental distinction is made between -source and binary-only NMUs, which is explained in the next section. - - Terminology -

-There are two new terms used throughout this section: ``binary-only NMU'' -and ``source NMU''. These terms are used with specific technical -meaning throughout this document. Both binary-only and source NMUs are -similar, since they involve an upload of a package by a developer who -is not the official maintainer of that package. That is why it's a -non-maintainer upload. -

-A source NMU is an upload of a package by a developer who is not the -official maintainer, for the purposes of fixing a bug in the package. -Source NMUs always involves changes to the source (even if it is just -a change to debian/changelog). This can be either a -change to the upstream source, or a change to the Debian bits of the -source. Note, however, that source NMUs may also include -architecture-dependent packages, as well as an updated Debian diff. -

-A binary-only NMU is a recompilation and upload of a binary package -for a given architecture. As such, it is usually part of a porting -effort. A binary-only NMU is a non-maintainer uploaded binary version -of a package, with no source changes required. There are many cases -where porters must fix problems in the source in order to get them to -compile for their target architecture; that would be considered a -source NMU rather than a binary-only NMU. As you can see, we don't -distinguish in terminology between porter NMUs and non-porter NMUs. +name="dpkg-scanpackages" section="8"> and +.

-Both classes of NMUs, source and binary-only, can be lumped by the -term ``NMU''. However, this often leads to confusion, since most -people think ``source NMU'' when they think ``NMU''. So it's best to -be careful. In this chapter, if we use the unqualified term ``NMU'', -we refer to any type of non-maintainer upload NMUs, whether source and -binary, or binary-only. +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, . - Who can do an NMU + Handling package bugs

-Only official, registered Debian maintainers can do binary or source -NMUs. An official maintainer is someone who has their key in the -Debian key ring. Non-developers, however, are encouraged to download -the source package and start hacking on it to fix problems; however, -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. - +Often as a package maintainer, you find bugs in other packages or else +have bugs reported to your packages which need to be reassigned. The + can tell you how +to do this. Some information on filing bugs can be found in . - When to do a source NMU + Monitoring bugs

-Guidelines for when to do a source NMU depend on the target -distribution, i.e., stable, unstable, or experimental. Porters have -slightly different rules than non-porters, due to their unique -circumstances (see ). +If you want to be a good maintainer, you should periodically check the + for your +packages. The BTS contains all the open bugs against your packages. +You can check them by browsing this page: +http://&bugs-host;/yourlogin@debian.org.

-When a security bug is detected, the security team may do an NMU. -Please refer to for more information. +Maintainers interact with the BTS via email addresses at +&bugs-host;. Documentation on available commands can be +found at , or, if you have installed the +doc-debian package, you can look at the local files +&file-bts-docs;.

-During the release cycle (see ), NMUs which fix -serious or higher severity bugs are encouraged and accepted. Even -during this window, however, you should endeavor to reach the current -maintainer of the package; they might be just about to upload a fix -for the problem. As with any source NMU, the guidelines found in need to be followed. Special exceptions are made -for . +Some find it useful to get periodic reports on open bugs. You can add +a cron job such as the following if you want to get a weekly email +outlining all the open bugs against your packages: + +# ask for weekly reports of bugs in my packages +&cron-bug-report; + +Replace address with your official Debian +maintainer address. + + Responding to bugs

-Uploading bug fixes to unstable by non-maintainers should only be done -by following this protocol: +Make sure that any discussion you have about bugs are sent both to +the original submitter of the bug, and the bug itself (e.g., +123@bugs.debian.org). If you're writing a new +mail and you don't remember the submitter email address, you can +use the 123-submitter@bugs.debian.org email to +contact the submitter and to record your mail within the +bug log (that means you don't need to send a copy of the mail to +123@bugs.debian.org).

- - -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 -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. -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. -Make sure your patch is as small and as non-disruptive as it can be. - -Upload your package to incoming in DELAYED/7-day (cf. -), send the final patch to the maintainer via -the BTS, and explain to them that they have 7 days to react if they want -to cancel the NMU. - -Follow what happens, you're responsible for any bug that you introduced -with your NMU. You should probably use (PTS) -to stay informed of the state of the package after your NMU. - +Once you've dealt with a bug report (e.g. fixed it), mark it as +done (close it) by sending an explanation message to +123-done@bugs.debian.org. If you're fixing a bug by +changing and uploading the package, you can automate bug closing as +described in .

-At times, the release manager or an organized group of developers can -announce a certain period of time in which the NMU rules are relaxed. -This usually involves shortening the period during which one is to wait -before uploading the fixes, and shortening the DELAYED period. It is -important to notice that even in these so-called "bug squashing party" -times, the NMU'er has to file bugs and contact the developer first, -and act later. +You should never close bugs via the bug server close +command sent to &email-bts-control;. If you do so, the original +submitter will not receive any information about why the bug was +closed. - How to do a source NMU -

-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 -simply uploading a recompiled binary package, the rules are different; -see . + Bug housekeeping

-First and foremost, it is critical that NMU patches to source should -be as non-disruptive as possible. Do not do housekeeping tasks, do -not change the name of modules or files, do not move directories; in -general, do not fix things which are not broken. Keep the patch as -small as possible. If things bother you aesthetically, talk to the -Debian maintainer, talk to the upstream maintainer, or submit a bug. -However, aesthetic changes must not be made in a non-maintainer -upload. - - - Source NMU version numbering -

-Whenever you have made a change to a package, no matter how trivial, -the version number needs to change. This enables our packing system -to function. -

-If you are doing a non-maintainer upload (NMU), you should add a new -minor version number to the debian-revision part of the -version number (the portion after the last hyphen). This extra minor -number will start at `1'. For example, consider the package `foo', -which is at version 1.1-3. In the archive, the source package control -file would be foo_1.1-3.dsc. The upstream version is -`1.1' and the Debian revision is `3'. The next NMU would add a new -minor number `.1' to the Debian revision; the new source control file -would be foo_1.1-3.1.dsc. -

-The Debian revision minor number is needed to avoid stealing one of -the package maintainer's version numbers, which might disrupt their -work. It also has the benefit of making it visually clear that a -package in the archive was not made by the official maintainer. -

-If there is no debian-revision component in the version -number then one should be created, starting at `0.1'. If it is -absolutely necessary for someone other than the usual maintainer to -make a release based on a new upstream version then the person making -the release should start with the debian-revision value -`0.1'. The usual maintainer of a package should start their -debian-revision numbering at `1'. - - - - Source NMUs must have a new changelog entry -

-A non-maintainer doing a source NMU must create a changelog entry, -describing which bugs are fixed by the NMU, and generally why the NMU -was required and what it fixed. The changelog entry will have the -non-maintainer's email address in the log entry and the NMU version -number in it. -

-By convention, source NMU changelog entries start with the line - - * Non-maintainer upload - - - - Source NMUs and the Bug Tracking System -

-Maintainers other than the official package maintainer should make as -few changes to the package as possible, and they should always send a -patch as a unified context diff (diff -u) detailing their -changes to the Bug Tracking System. -

-What if you are simply recompiling the package? If you just need to -recompile it for a single architecture, then you may do a binary-only -NMU as described in which doesn't require any -patch to be sent. If you want the package to be recompiled for all -architectures, then you do a source NMU as usual and you will have to -send a patch. -

-If the source NMU (non-maintainer upload) fixes some existing bugs, -these bugs should be tagged fixed in the Bug Tracking -System rather than closed. By convention, only the official package -maintainer or the original bug submitter are allowed to close bugs. -Fortunately, Debian's archive system recognizes NMUs and thus marks -the bugs fixed in the NMU appropriately if the person doing the NMU -has listed all bugs in the changelog with the Closes: -bug#nnnnn syntax (see for -more information describing how to close bugs via the changelog). -Tagging the bugs fixed ensures that everyone knows that the -bug was fixed in an NMU; however the bug is left open until the -changes in the NMU are incorporated officially into the package by -the official package maintainer. -

-Also, after doing an NMU, you have to open a new bug and include a -patch showing all the changes you have made. Alternatively you can send -that information to the existing bugs that are fixed by your NMU. -The normal maintainer will either apply the patch or employ an alternate -method of fixing the problem. Sometimes bugs are fixed independently -upstream, which is another good reason to back out an NMU's patch. -If the maintainer decides not to apply the NMU's patch but to release a -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. - - - Building source NMUs -

-Source NMU packages are built normally. Pick a distribution using the -same rules as found in . Just as described in -, a normal changes file, etc., will be built. In -fact, all the prescriptions from apply. -

-Make sure you do not change the value of the maintainer in -the debian/control file. Your name as given in the NMU entry of -the debian/changelog file will be used for signing the -changes file. +As a package maintainer, you will often find bugs in other packages or +have bugs reported against your packages which are actually bugs in +other packages. The bug tracking system's features interesting to developers +are described in the . Operations such as reassigning, merging, and tagging +bug reports are described in the . This section contains +some guidelines for managing your own bugs, based on the collective +Debian developer experience. +

+Filing bugs for problems that you find in other packages is one of +the "civic obligations" of maintainership, see +for details. However, handling the bugs in your own packages is +even more important. +

+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 +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, +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. +If this situation is unacceptable, you (or the submitter) may want to +require a decision of the technical committee by reassigning the bug +to tech-ctte (you may use the clone command of +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 +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. +

+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 +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 +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 +on how to reproduce it. After a few months, if this information has not +been sent by someone, the bug may be closed. + +If the bug is related to the packaging, you just fix it. If you are not +able to fix it yourself, then tag the bug as help. You can +also ask for help on &email-debian-devel; or &email-debian-qa;. If it's an +upstream problem, you have to forward it to the upstream author. +Forwarding a bug is not enough, you have to check at each release if +the bug has been fixed or not. If it has, you just close it, otherwise +you have to remind the author about it. If you have the required skills +you can prepare a patch that fixes the bug and that you send at the +same time to the author. Make sure to send the patch in the BTS and to +tag the bug as patch. + +If you have fixed a bug in your local copy, or if a fix has been +committed to the CVS repository, you may tag the bug as +pending to let people know that the bug is corrected and that +it will be closed with the next upload (add the closes: in +the changelog). This is particularly useful if you +are several developers working on the same package. + +Once a corrected package is available in the unstable +distribution, you can close the bug. This can be done automatically, +read . + - Acknowledging an NMU + When bugs are closed by new uploads

-If one of your packages has been NMU'ed, you have to incorporate the -changes in your copy of the sources. This is easy, you just have -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. You -can either 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. +If you fix a bug in your packages, it is your responsibility as the +package maintainer to close the bug when it has been fixed. However, +you should not close the bug until the package which fixes the bug has +been accepted into the Debian archive. Therefore, once you get +notification that your updated package has been installed into the +archive, you can and should close the bug in the BTS.

-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 -basis as co-maintainer or backup maintainer -(see ). +However, it's possible to avoid having to manually close bugs after the +upload -- just list the fixed bugs in your debian/changelog +file, following a certain syntax, and the archive maintenance software +will close the bugs for you. For example: + +acme-cannon (3.1415) unstable; urgency=low - Porting and being ported -

-Debian supports an ever-increasing number of architectures. Even if -you are not a porter, and you don't use any architecture but one, it -is part of your duty as a maintainer to be aware of issues of -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 -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 -a recompile for each architecture, which amounts to -&number-of-arches; more builds. + * Frobbed with options (closes: Bug#98339) + * Added safety to prevent operator dismemberment, closes: bug#98765, + bug#98713, #98714. + * Added man page. Closes: #98725. + +Technically speaking, the following Perl regular expression is what is +used: + + /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig + - Being kind to porters -

-Porters have a difficult and unique task, since they are required to -deal with a large volume of packages. Ideally, every source package -should build right out of the box. Unfortunately, this is often not -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 author prefers the closes: #XXX syntax, as +one of the most concise and easiest to integrate with the text of the +changelog.

-The first and most important watchword 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, -doing your best to hunt down whatever the problem is. +If you happen to mistype a bug number or forget one in the changelog file, +don't hesitate to undo any damage the error caused. To reopen wrongly closed +bugs, send an reopen XXX command in the bug tracking +system's control bot. To close any remaining bugs that were fixed by your +upload, email the .changes file to +XXX-done@bugs.debian.org, where XXX is your +bug number.

-By far, most of the problems encountered by porters are caused by -packaging bugs in the source packages. Here is a checklist -of things you should check or be aware of. +Bear in mind that it is not obligatory to close bugs using the changelog +like described above -- if you simply want to close bugs that don't have +anything to do with an upload of yours, do it simply by emailing an +explanation to XXX-done@bugs.debian.org. - - -Make sure that your Build-Depends and -Build-Depends-Indep settings in debian/control -are set properly. The best way to validate this is to use the -debootstrap package to create an unstable chroot -environment. Within that chrooted environment, install the -build-essential package and any package -dependencies mentioned in Build-Depends and/or -Build-Depends-Indep. Finally, try building your package -within that chrooted environment. These steps can be automated -by the use of the pbuilder program which is provided by -the package of the same name. -

-See the for instructions on setting build dependencies. - -Don't set architecture to a value other than ``all'' or ``any'' unless -you really mean it. In too many cases, maintainers don't follow the -instructions in the . Setting your architecture to ``i386'' is usually incorrect. - -Make sure your source package is correct. Do dpkg-source -x -package.dsc to make sure your source package unpacks -properly. Then, in there, try building your package from scratch with -dpkg-buildpackage. - -Make sure you don't ship your source package with the -debian/files or debian/substvars files. -They should be removed by the `clean' target of -debian/rules. - -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 -machine, even if it's the same architecture. - -Don't depend on the package you're building already being installed (a -sub-case of the above issue). - -Don't rely on the compiler being a certain version, if possible. If -not, then make sure your build dependencies reflect the restrictions, -although you are probably asking for trouble, since different -architectures sometimes standardize on different compilers. - -Make sure your debian/rules contains separate ``binary-arch'' and -``binary-indep'' targets, as the Debian Policy Manual requires. -Make sure that both targets work independently, that is, that you can -call the target without having called the other before. To test this, -try to run dpkg-buildpackage -b. - + Handling security-related bugs +

+Due to their sensitive nature, security-related bugs must be handled +carefully. The Debian Security Team exists to coordinate this +activity, keeping track of outstanding security problems, helping +maintainers with security problems or fix them themselves, sending +security advisories, and maintaining security.debian.org. + + - Guidelines for porter uploads -

-If the package builds out of the box for the architecture to be ported -to, you are in luck and your job is easy. This section applies to -that case; it describes how to build and upload your binary package so -that it is properly installed into the archive. If you do have to -patch the package in order to get it to compile for the other -architecture, you are actually doing a source NMU, so consult instead. -

-For a porter upload, no changes are being made to the source. You do -not need to touch any of the files in the source package. This -includes debian/changelog. -

-The way to invoke dpkg-buildpackage is as -dpkg-buildpackage -B -mporter-email. Of course, -set porter-email to your email address. This will do a -binary-only build of only the architecture-dependent portions of the -package, using the `binary-arch' target in debian/rules. + What to do when you learn of a + security problem +

+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;. +Useful information includes, for example: - - Recompilation or binary-only NMU -

-Sometimes the initial porter upload is problematic because the environment -in which the package was built was not good enough (outdated or obsolete -library, bad compiler, ...). Then you may just need to recompile it in -an updated environment. However, you have to bump the version number in -this case, so that the old bad package can be replaced in the Debian archive -(katie refuses to install new packages if they don't have a -version number greater than the currently available one). Despite the -required modification of the changelog, these are called binary-only NMUs -— there is no need in this case to trigger all other architectures -to consider themselves out of date or requiring recompilation. -

-Such recompilations require special ``magic'' version numbering, so that -the archive maintenance tools recognize that, even though there is a -new Debian version, there is no corresponding source update. If you -get this wrong, the archive maintainers will reject your upload (due -to lack of corresponding source code). -

-The ``magic'' for a recompilation-only NMU is triggered by using the -third-level number on the Debian part of the version. For instance, -if the latest version you are recompiling against was version -``2.9-3'', your NMU should carry a version of ``2.9-3.0.1''. If the -latest version was ``3.4-2.1'', your NMU should have a version number -of ``3.4-2.1.1''. + + What versions of the package are known to be affected by the + bug. Check each version that is present in a supported Debian + release, as well as testing and unstable. + The nature of the fix, if any is available (patches are + especially helpful) - - When to do a source NMU if you are a porter -

-Porters doing a source NMU generally follow the guidelines found in -, just like non-porters. However, it is expected that -the wait cycle for a porter's source NMU is smaller than for a -non-porter, since porters have to cope with a large quantity of -packages. -Again, the situation varies depending on the distribution they are -uploading to. + Any fixed packages that you have prepared yourself (send only + the .diff.gz and .dsc files) - -

-However, if you are a porter doing an NMU for `unstable', the above -guidelines for porting should be followed, with two variations. -Firstly, the acceptable waiting period — the time between when the -bug is submitted to the BTS and when it is OK to do an NMU — is seven -days for porters working on the unstable distribution. This period -can be shortened if the problem is critical and imposes hardship on -the porting effort, at the discretion of the porter group. (Remember, -none of this is Policy, just mutually agreed upon guidelines.) -

-Secondly, porters doing source NMUs should make sure that the bug they -submit to the BTS should be of severity `serious' or greater. This -ensures that a single source package can be used to compile every -supported Debian architecture by release time. It is very important -that we have one version of the binary and source package for all -architecture in order to comply with many licenses. -

-Porters should try to avoid patches which simply kludge around bugs in -the current version of the compile environment, kernel, or libc. -Sometimes such kludges can't be helped. If you have to kludge around -compilers bugs and the like, make sure you #ifdef your work -properly; also, document your kludge so that people know to remove it -once the external problems have been fixed. -

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

+Unlike most other activities within Debian, information about security +issues must sometimes be kept private for a time. Whether this is the +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: + + + he notices it on a public forum (mailing list, web site, etc.) + someone files a bug report + someone informs him via private email + + + In the first two cases, the information is public and it is important + to have a fix as soon as possible. In the last case, however, it + might not be public information. In that case there are a few + possible options for dealing with the problem: + + + if it is a trivial problem (like insecure temporary files) + there is no need to keep the problem a secret and a fix should be + made and released. + + if the problem is severe (remotely exploitable, possibility to + gain root privileges) it is preferable to share the information with + other vendors and coordinate a release. The security team keeps + contacts with the various organizations and individuals and can take + care of that. + + +

+ In all cases if the person who reports the problem asks to not + disclose the information that should be respected, with the obvious + exception of informing the security team (make sure you tell the + security team that the information can not be disclosed). + +

+Please note that if secrecy is needed you can also not upload a fix to +unstable (or anywhere else), since the changelog and diff information +for unstable is 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 +or exploit has become public. + + Security Advisories +

+Security advisories are only issued for the current, released stable +distribution, not for testing or unstable. When released, advisories +are sent to the &email-debian-security-announce; +mailing list and posted on . +Security advisories are written and posted by the security +team. However they certainly do not mind if a maintainer can supply +some of the information for them, or write part of the +text. Information that should be in an advisory includes: + + + A description of the problem and its scope, including: + + The type of problem (privilege escalation, denial of + service, etc.) + How it can be exploited + Whether it is remotely or locally exploitable + How the problem was fixed + + Version numbers of affected packages + Version numbers of fixed packages + Information on where to obtain the updated packages + References to upstream advisories, identifiers, and any other + information useful in cross-referencing the vulnerability + + + + Preparing packages to address security issues +

+One way that you can assist the security team in their duties is to +provide fixed packages suitable for a security advisory for the stable +Debian release. +

+ When an update is made to the stable release, care must be taken to + avoid changing system behavior or introducing new bugs. In order to + do this, make as few changes as possible to fix the bug. Users and + administrators rely on the exact behavior of a release once it is + made, so any change that is made might break someone's system. + This is especially true of libraries: make sure you never change the + API or ABI, no matter how small the change. +

+This means that moving to a new upstream version is not a good +solution. Instead, the relevant changes should be back-ported to the +version present in the current stable Debian release. Generally, +upstream maintainers are willing to help if needed. If not, the +Debian security team may be able to help. +

+In some cases, it is not possible to back-port a security fix, for +example when large amounts of source code need to be modified or +rewritten. If this happens, it may be necessary to move to a new +upstream version. However, you must always coordinate that with the +security team beforehand. +

+Related to this is another important guideline: always test your +changes. If you have an exploit available, try it and see if it +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. +

+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). + +When packaging the fix, keep the following points in mind: + + + Make sure you 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! + + Make sure the version number is proper. It must be greater + than the current package, but less than package versions in later + distributions. If in doubt, test it with dpkg + --compare-versions. For testing, there must be + a higher version in unstable. If there is none yet (for example, + if testing and unstable have the same version) you must upload a + new version to unstable first. + Do not make source-only uploads if your package has any + binary-all packages (do not use the -S option to + dpkg-buildpackage). The buildd infrastructure will + not build those. This point applies to normal package uploads as + well. - - Porting infrastructure and automation -

-There is infrastructure and several tools to help automate the package -porting. This section contains a brief overview of this automation and -porting to these tools; see the package documentation or references for -full information.

+ If 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). - - Mailing lists and web pages -

-Web pages containing the status of each port can be found at . -

-Each port of Debian has a mailing list. The list of porting mailing -lists can be found at . These lists -are used to coordinate porters, and to connect the users of a given -port with the porters.

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

-Descriptions of several porting tools can be found in .

- + Be sure, when compiling a package, to compile 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 ) + or setup a chroot (see and + ). + - - buildd -

-The buildd system is used as a distributed, -client-server build distribution system. It is usually used in -conjunction with auto-builders, which are ``slave'' hosts -which simply check out and attempt to auto-build packages which need -to be ported. There is also an email interface to the system, which -allows porters to ``check out'' a source package (usually one which -cannot yet be auto-built) and work on it. -

-buildd is not yet available as a package; however, -most porting efforts are either using it currently or planning to use -it in the near future. The actual automated builder is packaged as -sbuild, see its description in . -The complete buildd system also collects a number of as yet unpackaged -components which are currently very useful and in use continually, -such as andrea and -wanna-build. -

-Some of the data produced by buildd which is -generally useful to porters is available on the web at . This data includes nightly updated information -from andrea (source dependencies) and -quinn-diff (packages needing recompilation). -

-We are quite proud of this system, since it has so -many possible uses. Independent development groups can use the system for -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. - + Uploading the fixed package +

+DO NOT upload a package to the security upload queue 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. +

+DO NOT upload your fix to proposed-updates without +coordinating with the security team. Packages from +security.debian.org will be copied into the proposed-updates directory +automatically. If a package with the same or a higher version number +is already installed into the archive, the security update will be +rejected by the archive system. That way, the stable distribution +will end up without a security update for this package instead. +

+Once you have created and tested the new package and it has been +approved by the security team, it needs to be uploaded so that it can +be installed in the archives. For security uploads, the place to +upload to is +ftp://security.debian.org/pub/SecurityUploadQueue/ . +

+Once an upload to the security queue has been accepted, the package +will automatically be rebuilt for all architectures and stored for +verification by the security team. +

+Uploads which are waiting for acceptance or verification are only +accessible by the security team. This is necessary since there might +be fixes for security problems that cannot be disclosed yet. + +

+If a member of the security team accepts a package, it will be +installed on security.debian.org as well as the proper +distribution-proposed-updates on ftp-master or in the non-US +archive. - - Collaborative maintenance -

-"Collaborative maintenance" is a term describing the sharing of Debian -package maintenance duties by several people. This collaboration is -almost always a good idea, since it generally results in higher quality and -faster bug fix turnaround time. It is strongly recommended that -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 -the Maintainer field of the debian/control file. -Co-maintainers are all the other maintainers.

-

-In its most basic form, the process of adding a new co-maintainer is -quite easy: - -

-Setup the co-maintainer with access to the sources you build the -package from. Generally this implies you are using a network-capable -version control system, such as CVS or -Subversion.

- - -

-Add the co-maintainer's correct maintainer name and address to the -Uploaders field in the global part of the -debian/control file. - -Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org> - -

- - -

-Using the PTS (), the co-maintainers -should subscribe themselves to the appropriate source package.

- -

- Moving, removing, renaming, adopting, and orphaning @@ -2493,419 +2375,552 @@ make sure that the old maintainer has no problem with the fact that they will continue to receive the bugs during that time. - Handling package bugs -

-Often as a package maintainer, you find bugs in other packages or else -have bugs reported to your packages which need to be reassigned. The - can tell you how -to do this. Some information on filing bugs can be found in . + Porting and being ported +

+Debian supports an ever-increasing number of architectures. Even if +you are not a porter, and you don't use any architecture but one, it +is part of your duty as a maintainer to be aware of issues of +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 +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 +a recompile for each architecture, which amounts to +&number-of-arches; more builds. - Monitoring bugs + + Being kind to porters

-If you want to be a good maintainer, you should periodically check the - for your -packages. The BTS contains all the open bugs against your packages. -You can check them by browsing this page: -http://&bugs-host;/yourlogin@debian.org. +Porters have a difficult and unique task, since they are required to +deal with a large volume of packages. Ideally, every source package +should build right out of the box. Unfortunately, this is often not +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.

-Maintainers interact with the BTS via email addresses at -&bugs-host;. Documentation on available commands can be -found at , or, if you have installed the -doc-debian package, you can look at the local files -&file-bts-docs;. +The first and most important watchword 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, +doing your best to hunt down whatever the problem is.

-Some find it useful to get periodic reports on open bugs. You can add -a cron job such as the following if you want to get a weekly email -outlining all the open bugs against your packages: - -# ask for weekly reports of bugs in my packages -&cron-bug-report; - -Replace address with your official Debian -maintainer address. +By far, most of the problems encountered by porters are caused by +packaging bugs in the source packages. Here is a checklist +of things you should check or be aware of. + + + +Make sure that your Build-Depends and +Build-Depends-Indep settings in debian/control +are set properly. The best way to validate this is to use the +debootstrap package to create an unstable chroot +environment. Within that chrooted environment, install the +build-essential package and any package +dependencies mentioned in Build-Depends and/or +Build-Depends-Indep. Finally, try building your package +within that chrooted environment. These steps can be automated +by the use of the pbuilder program which is provided by +the package of the same name. +

+See the for instructions on setting build dependencies. + +Don't set architecture to a value other than ``all'' or ``any'' unless +you really mean it. In too many cases, maintainers don't follow the +instructions in the . Setting your architecture to ``i386'' is usually incorrect. + +Make sure your source package is correct. Do dpkg-source -x +package.dsc to make sure your source package unpacks +properly. Then, in there, try building your package from scratch with +dpkg-buildpackage. + +Make sure you don't ship your source package with the +debian/files or debian/substvars files. +They should be removed by the `clean' target of +debian/rules. + +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 +machine, even if it's the same architecture. + +Don't depend on the package you're building already being installed (a +sub-case of the above issue). + +Don't rely on the compiler being a certain version, if possible. If +not, then make sure your build dependencies reflect the restrictions, +although you are probably asking for trouble, since different +architectures sometimes standardize on different compilers. + +Make sure your debian/rules contains separate ``binary-arch'' and +``binary-indep'' targets, as the Debian Policy Manual requires. +Make sure that both targets work independently, that is, that you can +call the target without having called the other before. To test this, +try to run dpkg-buildpackage -b. + - Responding to bugs + + Guidelines for porter uploads

-Make sure that any discussion you have about bugs are sent both to -the original submitter of the bug, and the bug itself (e.g., -123@bugs.debian.org). If you're writing a new -mail and you don't remember the submitter email address, you can -use the 123-submitter@bugs.debian.org email to -contact the submitter and to record your mail within the -bug log (that means you don't need to send a copy of the mail to -123@bugs.debian.org). +If the package builds out of the box for the architecture to be ported +to, you are in luck and your job is easy. This section applies to +that case; it describes how to build and upload your binary package so +that it is properly installed into the archive. If you do have to +patch the package in order to get it to compile for the other +architecture, you are actually doing a source NMU, so consult instead.

-Once you've dealt with a bug report (e.g. fixed it), mark it as -done (close it) by sending an explanation message to -123-done@bugs.debian.org. If you're fixing a bug by -changing and uploading the package, you can automate bug closing as -described in . +For a porter upload, no changes are being made to the source. You do +not need to touch any of the files in the source package. This +includes debian/changelog.

-You should never close bugs via the bug server close -command sent to &email-bts-control;. If you do so, the original -submitter will not receive any information about why the bug was -closed. +The way to invoke dpkg-buildpackage is as +dpkg-buildpackage -B -mporter-email. Of course, +set porter-email to your email address. This will do a +binary-only build of only the architecture-dependent portions of the +package, using the `binary-arch' target in debian/rules. - Bug housekeeping + + Recompilation or binary-only NMU

-As a package maintainer, you will often find bugs in other packages or -have bugs reported against your packages which are actually bugs in -other packages. The bug tracking system's features interesting to developers -are described in the . Operations such as reassigning, merging, and tagging -bug reports are described in the . This section contains -some guidelines for managing your own bugs, based on the collective -Debian developer experience. -

-Filing bugs for problems that you find in other packages is one of -the "civic obligations" of maintainership, see -for details. However, handling the bugs in your own packages is -even more important. -

-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 -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, -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. -If this situation is unacceptable, you (or the submitter) may want to -require a decision of the technical committee by reassigning the bug -to tech-ctte (you may use the clone command of -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 -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. -

-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 -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 -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 -on how to reproduce it. After a few months, if this information has not -been sent by someone, the bug may be closed. - -If the bug is related to the packaging, you just fix it. If you are not -able to fix it yourself, then tag the bug as help. You can -also ask for help on &email-debian-devel; or &email-debian-qa;. If it's an -upstream problem, you have to forward it to the upstream author. -Forwarding a bug is not enough, you have to check at each release if -the bug has been fixed or not. If it has, you just close it, otherwise -you have to remind the author about it. If you have the required skills -you can prepare a patch that fixes the bug and that you send at the -same time to the author. Make sure to send the patch in the BTS and to -tag the bug as patch. - -If you have fixed a bug in your local copy, or if a fix has been -committed to the CVS repository, you may tag the bug as -pending to let people know that the bug is corrected and that -it will be closed with the next upload (add the closes: in -the changelog). This is particularly useful if you -are several developers working on the same package. - -Once a corrected package is available in the unstable -distribution, you can close the bug. This can be done automatically, -read . - - - Handling security-related bugs -

-Due to their sensitive nature, security-related bugs must be handled -carefully. The Debian Security Team exists to coordinate this -activity, keeping track of outstanding security problems, helping -maintainers with security problems or fix them themselves, sending -security advisories, and maintaining security.debian.org. - - - - - What to do when you learn of a - security problem -

-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;. -Useful information includes, for example: +Sometimes the initial porter upload is problematic because the environment +in which the package was built was not good enough (outdated or obsolete +library, bad compiler, ...). Then you may just need to recompile it in +an updated environment. However, you have to bump the version number in +this case, so that the old bad package can be replaced in the Debian archive +(katie refuses to install new packages if they don't have a +version number greater than the currently available one). Despite the +required modification of the changelog, these are called binary-only NMUs +— there is no need in this case to trigger all other architectures +to consider themselves out of date or requiring recompilation. +

+Such recompilations require special ``magic'' version numbering, so that +the archive maintenance tools recognize that, even though there is a +new Debian version, there is no corresponding source update. If you +get this wrong, the archive maintainers will reject your upload (due +to lack of corresponding source code). +

+The ``magic'' for a recompilation-only NMU is triggered by using the +third-level number on the Debian part of the version. For instance, +if the latest version you are recompiling against was version +``2.9-3'', your NMU should carry a version of ``2.9-3.0.1''. If the +latest version was ``3.4-2.1'', your NMU should have a version number +of ``3.4-2.1.1''. - - What versions of the package are known to be affected by the - bug. Check each version that is present in a supported Debian - release, as well as testing and unstable. - The nature of the fix, if any is available (patches are - especially helpful) + + When to do a source NMU if you are a porter +

+Porters doing a source NMU generally follow the guidelines found in +, just like non-porters. However, it is expected that +the wait cycle for a porter's source NMU is smaller than for a +non-porter, since porters have to cope with a large quantity of +packages. +Again, the situation varies depending on the distribution they are +uploading to. - Any fixed packages that you have prepared yourself (send only - the .diff.gz and .dsc files) + +

+However, if you are a porter doing an NMU for `unstable', the above +guidelines for porting should be followed, with two variations. +Firstly, the acceptable waiting period — the time between when the +bug is submitted to the BTS and when it is OK to do an NMU — is seven +days for porters working on the unstable distribution. This period +can be shortened if the problem is critical and imposes hardship on +the porting effort, at the discretion of the porter group. (Remember, +none of this is Policy, just mutually agreed upon guidelines.) +

+Secondly, porters doing source NMUs should make sure that the bug they +submit to the BTS should be of severity `serious' or greater. This +ensures that a single source package can be used to compile every +supported Debian architecture by release time. It is very important +that we have one version of the binary and source package for all +architecture in order to comply with many licenses. +

+Porters should try to avoid patches which simply kludge around bugs in +the current version of the compile environment, kernel, or libc. +Sometimes such kludges can't be helped. If you have to kludge around +compilers bugs and the like, make sure you #ifdef your work +properly; also, document your kludge so that people know to remove it +once the external problems have been fixed. +

+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. - - Confidentiality + + Porting infrastructure and automation

-Unlike most other activities within Debian, information about security -issues must sometimes be kept private for a time. Whether this is the -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: - - - he notices it on a public forum (mailing list, web site, etc.) - someone files a bug report - someone informs him via private email - - - In the first two cases, the information is public and it is important - to have a fix as soon as possible. In the last case, however, it - might not be public information. In that case there are a few - possible options for dealing with the problem: +There is infrastructure and several tools to help automate the package +porting. This section contains a brief overview of this automation and +porting to these tools; see the package documentation or references for +full information.

- - if it is a trivial problem (like insecure temporary files) - there is no need to keep the problem a secret and a fix should be - made and released. + + Mailing lists and web pages +

+Web pages containing the status of each port can be found at . +

+Each port of Debian has a mailing list. The list of porting mailing +lists can be found at . These lists +are used to coordinate porters, and to connect the users of a given +port with the porters.

+ - if the problem is severe (remotely exploitable, possibility to - gain root privileges) it is preferable to share the information with - other vendors and coordinate a release. The security team keeps - contacts with the various organizations and individuals and can take - care of that. - + + Porter tools +

+Descriptions of several porting tools can be found in .

+ -

- In all cases if the person who reports the problem asks to not - disclose the information that should be respected, with the obvious - exception of informing the security team (make sure you tell the - security team that the information can not be disclosed). + + buildd +

+The buildd system is used as a distributed, +client-server build distribution system. It is usually used in +conjunction with auto-builders, which are ``slave'' hosts +which simply check out and attempt to auto-build packages which need +to be ported. There is also an email interface to the system, which +allows porters to ``check out'' a source package (usually one which +cannot yet be auto-built) and work on it. +

+buildd is not yet available as a package; however, +most porting efforts are either using it currently or planning to use +it in the near future. The actual automated builder is packaged as +sbuild, see its description in . +The complete buildd system also collects a number of as yet unpackaged +components which are currently very useful and in use continually, +such as andrea and +wanna-build. +

+Some of the data produced by buildd which is +generally useful to porters is available on the web at . This data includes nightly updated information +from andrea (source dependencies) and +quinn-diff (packages needing recompilation). +

+We are quite proud of this system, since it has so +many possible uses. Independent development groups can use the system for +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. + -

-Please note that if secrecy is needed you can also not upload a fix to -unstable (or anywhere else), since the changelog and diff information -for unstable is 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 -or exploit has become public. + Non-Maintainer Uploads (NMUs) +

+Under certain circumstances it is necessary for someone other than the +official package maintainer to make a release of a package. This is +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 +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. +

+This chapter contains information providing guidelines for when and +how NMUs should be done. A fundamental distinction is made between +source and binary-only NMUs, which is explained in the next section. - Security Advisories -

-Security advisories are only issued for the current, released stable -distribution, not for testing or unstable. When released, advisories -are sent to the &email-debian-security-announce; -mailing list and posted on . -Security advisories are written and posted by the security -team. However they certainly do not mind if a maintainer can supply -some of the information for them, or write part of the -text. Information that should be in an advisory includes: + Terminology +

+There are two new terms used throughout this section: ``binary-only NMU'' +and ``source NMU''. These terms are used with specific technical +meaning throughout this document. Both binary-only and source NMUs are +similar, since they involve an upload of a package by a developer who +is not the official maintainer of that package. That is why it's a +non-maintainer upload. +

+A source NMU is an upload of a package by a developer who is not the +official maintainer, for the purposes of fixing a bug in the package. +Source NMUs always involves changes to the source (even if it is just +a change to debian/changelog). This can be either a +change to the upstream source, or a change to the Debian bits of the +source. Note, however, that source NMUs may also include +architecture-dependent packages, as well as an updated Debian diff. +

+A binary-only NMU is a recompilation and upload of a binary package +for a given architecture. As such, it is usually part of a porting +effort. A binary-only NMU is a non-maintainer uploaded binary version +of a package, with no source changes required. There are many cases +where porters must fix problems in the source in order to get them to +compile for their target architecture; that would be considered a +source NMU rather than a binary-only NMU. As you can see, we don't +distinguish in terminology between porter NMUs and non-porter NMUs. +

+Both classes of NMUs, source and binary-only, can be lumped by the +term ``NMU''. However, this often leads to confusion, since most +people think ``source NMU'' when they think ``NMU''. So it's best to +be careful. In this chapter, if we use the unqualified term ``NMU'', +we refer to any type of non-maintainer upload NMUs, whether source and +binary, or binary-only. - - A description of the problem and its scope, including: - - The type of problem (privilege escalation, denial of - service, etc.) - How it can be exploited - Whether it is remotely or locally exploitable - How the problem was fixed - - Version numbers of affected packages - Version numbers of fixed packages - Information on where to obtain the updated packages - References to upstream advisories, identifiers, and any other - information useful in cross-referencing the vulnerability - - - Preparing packages to address security issues -

-One way that you can assist the security team in their duties is to -provide fixed packages suitable for a security advisory for the stable -Debian release. -

- When an update is made to the stable release, care must be taken to - avoid changing system behavior or introducing new bugs. In order to - do this, make as few changes as possible to fix the bug. Users and - administrators rely on the exact behavior of a release once it is - made, so any change that is made might break someone's system. - This is especially true of libraries: make sure you never change the - API or ABI, no matter how small the change. -

-This means that moving to a new upstream version is not a good -solution. Instead, the relevant changes should be back-ported to the -version present in the current stable Debian release. Generally, -upstream maintainers are willing to help if needed. If not, the -Debian security team may be able to help. -

-In some cases, it is not possible to back-port a security fix, for -example when large amounts of source code need to be modified or -rewritten. If this happens, it may be necessary to move to a new -upstream version. However, you must always coordinate that with the -security team beforehand. -

-Related to this is another important guideline: always test your -changes. If you have an exploit available, try it and see if it -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. -

-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). + Who can do an NMU +

+Only official, registered Debian maintainers can do binary or source +NMUs. An official maintainer is someone who has their key in the +Debian key ring. Non-developers, however, are encouraged to download +the source package and start hacking on it to fix problems; however, +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. -When packaging the fix, keep the following points in mind: + When to do a source NMU +

+Guidelines for when to do a source NMU depend on the target +distribution, i.e., stable, unstable, or experimental. Porters have +slightly different rules than non-porters, due to their unique +circumstances (see ). +

+When a security bug is detected, the security team may do an NMU. +Please refer to for more information. +

+During the release cycle (see ), NMUs which fix +serious or higher severity bugs are encouraged and accepted. Even +during this window, however, you should endeavor to reach the current +maintainer of the package; they might be just about to upload a fix +for the problem. As with any source NMU, the guidelines found in need to be followed. Special exceptions are made +for . +

+Uploading bug fixes to unstable by non-maintainers should only be done +by following this protocol: +

- Make sure you 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! + +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 +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. +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. +Make sure your patch is as small and as non-disruptive as it can be. + +Upload your package to incoming in DELAYED/7-day (cf. +), send the final patch to the maintainer via +the BTS, and explain to them that they have 7 days to react if they want +to cancel the NMU. + +Follow what happens, you're responsible for any bug that you introduced +with your NMU. You should probably use (PTS) +to stay informed of the state of the package after your NMU. + +

+At times, the release manager or an organized group of developers can +announce a certain period of time in which the NMU rules are relaxed. +This usually involves shortening the period during which one is to wait +before uploading the fixes, and shortening the DELAYED period. It is +important to notice that even in these so-called "bug squashing party" +times, the NMU'er has to file bugs and contact the developer first, +and act later. - Make sure the version number is proper. It must be greater - than the current package, but less than package versions in later - distributions. If in doubt, test it with dpkg - --compare-versions. For testing, there must be - a higher version in unstable. If there is none yet (for example, - if testing and unstable have the same version) you must upload a - new version to unstable first. + How to do a source NMU +

+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 +simply uploading a recompiled binary package, the rules are different; +see . +

+First and foremost, it is critical that NMU patches to source should +be as non-disruptive as possible. Do not do housekeeping tasks, do +not change the name of modules or files, do not move directories; in +general, do not fix things which are not broken. Keep the patch as +small as possible. If things bother you aesthetically, talk to the +Debian maintainer, talk to the upstream maintainer, or submit a bug. +However, aesthetic changes must not be made in a non-maintainer +upload. - Do not make source-only uploads if your package has any - binary-all packages (do not use the -S option to - dpkg-buildpackage). The buildd infrastructure will - not build those. This point applies to normal package uploads as - well. - If 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). + Source NMU version numbering +

+Whenever you have made a change to a package, no matter how trivial, +the version number needs to change. This enables our packing system +to function. +

+If you are doing a non-maintainer upload (NMU), you should add a new +minor version number to the debian-revision part of the +version number (the portion after the last hyphen). This extra minor +number will start at `1'. For example, consider the package `foo', +which is at version 1.1-3. In the archive, the source package control +file would be foo_1.1-3.dsc. The upstream version is +`1.1' and the Debian revision is `3'. The next NMU would add a new +minor number `.1' to the Debian revision; the new source control file +would be foo_1.1-3.1.dsc. +

+The Debian revision minor number is needed to avoid stealing one of +the package maintainer's version numbers, which might disrupt their +work. It also has the benefit of making it visually clear that a +package in the archive was not made by the official maintainer. +

+If there is no debian-revision component in the version +number then one should be created, starting at `0.1'. If it is +absolutely necessary for someone other than the usual maintainer to +make a release based on a new upstream version then the person making +the release should start with the debian-revision value +`0.1'. The usual maintainer of a package should start their +debian-revision numbering at `1'. - 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, when compiling a package, to compile 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 ) - or setup a chroot (see and - ). - + + Source NMUs must have a new changelog entry +

+A non-maintainer doing a source NMU must create a changelog entry, +describing which bugs are fixed by the NMU, and generally why the NMU +was required and what it fixed. The changelog entry will have the +non-maintainer's email address in the log entry and the NMU version +number in it. +

+By convention, source NMU changelog entries start with the line + + * Non-maintainer upload + - Uploading the fixed package -

-DO NOT upload a package to the security upload queue 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. -

-DO NOT upload your fix to proposed-updates without -coordinating with the security team. Packages from -security.debian.org will be copied into the proposed-updates directory -automatically. If a package with the same or a higher version number -is already installed into the archive, the security update will be -rejected by the archive system. That way, the stable distribution -will end up without a security update for this package instead. -

-Once you have created and tested the new package and it has been -approved by the security team, it needs to be uploaded so that it can -be installed in the archives. For security uploads, the place to -upload to is -ftp://security.debian.org/pub/SecurityUploadQueue/ . -

-Once an upload to the security queue has been accepted, the package -will automatically be rebuilt for all architectures and stored for -verification by the security team. + Source NMUs and the Bug Tracking System +

+Maintainers other than the official package maintainer should make as +few changes to the package as possible, and they should always send a +patch as a unified context diff (diff -u) detailing their +changes to the Bug Tracking System. +

+What if you are simply recompiling the package? If you just need to +recompile it for a single architecture, then you may do a binary-only +NMU as described in which doesn't require any +patch to be sent. If you want the package to be recompiled for all +architectures, then you do a source NMU as usual and you will have to +send a patch. +

+If the source NMU (non-maintainer upload) fixes some existing bugs, +these bugs should be tagged fixed in the Bug Tracking +System rather than closed. By convention, only the official package +maintainer or the original bug submitter are allowed to close bugs. +Fortunately, Debian's archive system recognizes NMUs and thus marks +the bugs fixed in the NMU appropriately if the person doing the NMU +has listed all bugs in the changelog with the Closes: +bug#nnnnn syntax (see for +more information describing how to close bugs via the changelog). +Tagging the bugs fixed ensures that everyone knows that the +bug was fixed in an NMU; however the bug is left open until the +changes in the NMU are incorporated officially into the package by +the official package maintainer. +

+Also, after doing an NMU, you have to open a new bug and include a +patch showing all the changes you have made. Alternatively you can send +that information to the existing bugs that are fixed by your NMU. +The normal maintainer will either apply the patch or employ an alternate +method of fixing the problem. Sometimes bugs are fixed independently +upstream, which is another good reason to back out an NMU's patch. +If the maintainer decides not to apply the NMU's patch but to release a +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. -

-Uploads which are waiting for acceptance or verification are only -accessible by the security team. This is necessary since there might -be fixes for security problems that cannot be disclosed yet. -

-If a member of the security team accepts a package, it will be -installed on security.debian.org as well as the proper -distribution-proposed-updates on ftp-master or in the non-US -archive. + Building source NMUs +

+Source NMU packages are built normally. Pick a distribution using the +same rules as found in . Just as described in +, a normal changes file, etc., will be built. In +fact, all the prescriptions from apply. +

+Make sure you do not change the value of the maintainer in +the debian/control file. Your name as given in the NMU entry of +the debian/changelog file will be used for signing the +changes file. - When bugs are closed by new uploads + Acknowledging an NMU

-If you fix a bug in your packages, it is your responsibility as the -package maintainer to close the bug when it has been fixed. However, -you should not close the bug until the package which fixes the bug has -been accepted into the Debian archive. Therefore, once you get -notification that your updated package has been installed into the -archive, you can and should close the bug in the BTS. +If one of your packages has been NMU'ed, you have to incorporate the +changes in your copy of the sources. This is easy, you just have +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. You +can either 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.

-However, it's possible to avoid having to manually close bugs after the -upload -- just list the fixed bugs in your debian/changelog -file, following a certain syntax, and the archive maintenance software -will close the bugs for you. For example: - - -acme-cannon (3.1415) unstable; urgency=low +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 +basis as co-maintainer or backup maintainer +(see ). - * Frobbed with options (closes: Bug#98339) - * Added safety to prevent operator dismemberment, closes: bug#98765, - bug#98713, #98714. - * Added man page. Closes: #98725. - -Technically speaking, the following Perl regular expression is what is -used: + + Collaborative maintenance +

+"Collaborative maintenance" is a term describing the sharing of Debian +package maintenance duties by several people. This collaboration is +almost always a good idea, since it generally results in higher quality and +faster bug fix turnaround time. It is strongly recommended that +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 +the Maintainer field of the debian/control file. +Co-maintainers are all the other maintainers.

+

+In its most basic form, the process of adding a new co-maintainer is +quite easy: + +

+Setup the co-maintainer with access to the sources you build the +package from. Generally this implies you are using a network-capable +version control system, such as CVS or +Subversion.

+ + +

+Add the co-maintainer's correct maintainer name and address to the +Uploaders field in the global part of the +debian/control file. - /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig +Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org> - -The author prefers the closes: #XXX syntax, as -one of the most concise and easiest to integrate with the text of the -changelog. -

-If you happen to mistype a bug number or forget one in the changelog file, -don't hesitate to undo any damage the error caused. To reopen wrongly closed -bugs, send an reopen XXX command in the bug tracking -system's control bot. To close any remaining bugs that were fixed by your -upload, email the .changes file to -XXX-done@bugs.debian.org, where XXX is your -bug number. -

-Bear in mind that it is not obligatory to close bugs using the changelog -like described above -- if you simply want to close bugs that don't have -anything to do with an upload of yours, do it simply by emailing an -explanation to XXX-done@bugs.debian.org. - +

+ + +

+Using the PTS (), the co-maintainers +should subscribe themselves to the appropriate source package.

+ +

+ @@ -3009,8 +3024,8 @@ patches. See the package dbs for more information and hello-dbs for an example.

dpatch also provides these facilities, but it's intented to be -even easier to use. See the package dbs for documentation -and examples (in /usr/share/doc/dpatch). +even easier to use. See the package dpatch for +documentation and examples (in /usr/share/doc/dpatch). Multiple binary packages @@ -3088,10 +3103,14 @@ You can use this function to search $PATH for a command name, passed as an argument. It returns true (zero) if the command was found, and false if not. This is really the most portable way, since command -v, type, and which are not -POSIX. While which is an acceptable alternative, since +POSIX. +

+While which is an acceptable alternative, since it is from the required debianutils package, it's -not on the root partition, although that is probably not something -that will cause a problem. +not on the root partition. That is, it's in /usr/bin rather +than /bin, so one can't use it in scripts which are run +before the /usr partition is mounted. Most scripts won't have +this problem, though.