X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=ea0d883fe903f319eab9ed2a89aed08477b49e46;hp=f0c6956bee8964288c17634c8297026877c33033;hb=491b29a243ffc0be9f99bb12ac22c65ada8f96c4;hpb=bb52d6f47f4bf50354bb692fbdb39eebc5756af6 diff --git a/developers-reference.sgml b/developers-reference.sgml index f0c6956..ea0d883 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 @@ -264,18 +266,16 @@ available in . Maintaining your Debian information

-There's a LDAP database containing information about all -developers, you can access it at . You can -update your password (this password is propagated to most of the machines -that are accessible to you), your address, your country, the latitude and -longitude of the point where you live, phone and fax numbers, your -preferred shell, your IRC nickname, your web page and the email that -you're using as alias for your debian.org email. Most of the information -is not accessible to the public, for more details about this -database, please read its online documentation that you can find -at . +There's a LDAP database containing information about Debian developers at +. You should enter your information there and +update it as it changes. Most notably, make sure that the address where your +debian.org email gets forwarded to is always up to date, as well as the +address where you get your debian-private subscription if you choose to +subscribe there.

-You have to keep the information available there up-to-date. +For more information about the database, please see . + + Maintaining your public key

@@ -297,43 +297,54 @@ the documentation of the debian-keyring package. Voting

-Even if Debian is not always a real democracy, Debian has democratic -tools and uses a democratic process to elect its leader or -to approve a general resolution. Those processes are described in -the . +Even though Debian isn't really a democracy, we use a democratic +process to elect our leaders and to approve general resolutions. +These procedures are defined by the +. +

+Other than the yearly leader election, votes are not routinely held, and +they are not undertaken lightly. Each proposal is first discussed on +the &email-debian-vote; mailing list and it requires several endorsements +before the project secretary starts the voting procedure.

-Democratic processes work well only if everybody take part in the -vote, that's why you have to vote. To be able to vote you have to -subscribe to &email-debian-devel-announce; since call for votes are sent -there. If you want to follow the debate preceding a vote, you -may want to subscribe to &email-debian-vote;. +You don't have to track the pre-vote discussions, as the secretary will +issue several calls for votes on &email-debian-devel-announce; (and all +developers are expected to be subscribed to that list). Democracy doesn't +work well if people don't take part in the vote, which is why we encourage +all developers to vote. Voting is conducted via GPG-signed/encrypted emails +messages.

The list of all the proposals (past and current) is available on the - page. You will find -there additional information about how to make a vote proposal. + page, along with +information on how to make, second and vote on proposals. Going on vacation gracefully

-Most developers take vacations, and usually this means that they can't -work for Debian and they can't be reached by email if any problem occurs. -The other developers need to know that you're on vacation so that they'll -do whatever is needed when such a problem occurs. Usually this means that -other developers are allowed to NMU (see ) your package if a -big problem (release critical bugs, security update, etc.) occurs while -you're on vacation. +It is common for developers to have periods of absence, whether those are +planned vacations or simply being buried in other work. The important thing +to notice is that the other developers need to know that you're on vacation +so that they can do whatever is needed if a problem occurs with your +packages or other duties in the project. +

+Usually this means that other developers are allowed to NMU (see +) your package if a big problem (release critical bugs, +security update, etc.) occurs while you're on vacation. Sometimes it's +nothing as critical as that, but it's still appropriate to let the others +know that you're unavailable.

In order to inform the other developers, there's two things that you should do. -First send a mail to &email-debian-private; giving the period of time when -you will be on vacation. You can also give some special instructions on what to -do if any problem occurs. Be aware that some people don't care for vacation -notices and don't want to read them; you should prepend "[VAC] " to the -subject of your message so that it can be easily filtered. +First send a mail to &email-debian-private; with "[VAC] " prepended to the +subject of your messageThis is so that the message can be easily +filtered by people who don't want to read vacation notices. +and state the period of time when you will be on vacation. You can also give +some special instructions on what to do if a problem occurs.

-Next you should update your information -available in the Debian LDAP database and mark yourself as ``on vacation'' -(this information is only accessible to debian developers). Don't forget -to remove the ``on vacation'' flag when you come back! +The other thing to do is to mark yourself as "on vacation" in the +Debian developers' LDAP database (this +information is only accessible to Debian developers). +Don't forget to remove the "on vacation" flag when you come back! + Coordination with upstream developers

@@ -354,6 +365,7 @@ developers which can be included there, so that you won't have to modify the sources of the next upstream version. Whatever changes you need, always try not to fork from the upstream sources. + Managing release-critical bugs

Generally you should deal with bug reports on your packages as described in @@ -459,8 +471,10 @@ it to see the responses. Cross-posting (sending the same message to multiple lists) is discouraged. As ever on the net, please trim down the quoting of articles you're replying to. In general, please adhere to the usual conventions for -posting messages. Please read the for more information. +posting messages. +

+Please read the +for more information. Special lists

@@ -513,7 +527,7 @@ all the files. There are other additional channels dedicated to specific subjects. #debian-bugs is used for coordinating bug squash parties. #debian-boot is used to coordinate the work on the boot -floppies (i.e. the installer). #debian-doc is +floppies (i.e., the installer). #debian-doc is occasionally used to talk about documentation, like the document you are reading. Other channels are dedicated to an architecture or a set of packages: #debian-bsd, #debian-kde, #debian-jr, @@ -579,14 +593,14 @@ id="submit-bug"> for information on how to submit bugs. The bugs server

-bugs.debian.org is the canonical location for the Bug Tracking +&bugs-host; is the canonical location for the Bug Tracking System (BTS). If you plan on doing some statistical analysis or processing of Debian bugs, this would be the place to do it. Please describe your plans on &email-debian-devel; before implementing anything, however, to reduce unnecessary duplication of effort or wasted processing time.

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

@@ -611,7 +625,7 @@ bugs against the nonus.debian.org pseudo-package (notice the lack of hyphen between "non" and "us" in the pseudo-package name — that's for backwards compatibility). Remember to check whether or not someone else has already reported the problem on the -. +. The www-master server

@@ -623,7 +637,7 @@ If you find a problem with the Debian web server, you should generally submit a bug against the pseudo-package, www.debian.org. Remember to check whether or not someone else has already reported the problem on the -. +. The people web server

@@ -675,10 +689,22 @@ the finger service on Debian servers, try finger yourlogin@db.debian.org to see what it reports.

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 . +to change various information about themselves, such as: + + forwarding address for your debian.org email + subscription to debian-private + whether you are on vacation + personal information such as your address, country, + the latitude and longitude of the place where you live + for use in , phone and fax numbers, IRC nickname + and web page + password and preferred shell on Debian Project machines + +

+Most of the information is not accessible to the public, naturally. +For more information please read the online documentation that you can find +at .

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. @@ -761,6 +787,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 @@ -794,20 +827,6 @@ available at the . - Packages

@@ -908,7 +927,7 @@ Note that development under unstable continues during the freeze period, since the unstable distribution remains in place in parallel with testing. - Experimental + Experimental

The experimental distribution is a special distribution. It is not a full distribution in the same sense as `stable' and @@ -921,6 +940,13 @@ packages from experimental are expected to have been duly warned. In short, all bets are off for the experimental distribution.

+These are the lines for +experimental: + +deb http://ftp.xy.debian.org/debian/ ../project/experimental main +deb-src http://ftp.xy.debian.org/debian/ ../project/experimental main + +

If there is a chance that the software could do grave damage to a system, it is likely to be better to put it into experimental. For instance, an experimental compressed file system should probably go @@ -1043,7 +1069,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 @@ -1051,7 +1085,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 @@ -1088,6 +1122,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

@@ -1142,6 +1177,7 @@ In general, please refer to the for more information. It also includes answers to some of the frequently asked questions. + Package information

@@ -1213,7 +1249,11 @@ override disparity for the section or priority field). default Any non-automatic mail sent to the PTS by people who wanted to -contact the subscribers of the package. +contact the subscribers of the package. This can be done by sending mail +to srcpackage@&pts-host;. In order to prevent spam, +mails sent to these addresses must contain the header "X-PTS-Approved" +with a non-empty string. + summary @@ -1275,8 +1315,7 @@ various commands to pts@qa.debian.org. the list of available keywords: bts: mails coming from the Debian Bug Tracking System - bts-control: reply to mails sent to - control@bugs.debian.org + bts-control: reply to mails sent to &email-bts-control; summary: automatic summary mails about the state of a package cvs: notification of CVS commits ddtp: translations of descriptions and debconf templates @@ -1339,6 +1378,86 @@ notifications, you just have to make sure it sends a copy of those mails to srcpackage_cvs@&pts-host;. Only people who accepts the cvs keyword will receive the notifications. + The PTS web interface +

+The PTS has been extended with a web interface that puts together +many information about each source package. It features many useful +links (BTS, QA stats, contact information, DDTP translation status, +buildd logs) and gathers many more information from various places +(30 latest changelog entries, testing status, ...). It's a very useful +tool if you want to know what's going on with a specific source +package. Furthermore there's a form that let you easily subscribe to +the mail service offered by the PTS. +

+You can jump directly to the web page concerning a specific source package +with an url like http://&pts-host;/srcpackage. Otherwise +you can go through the . +

+This web interface has been designed like a portal for the development of +packages: you can add custom content on the pages of your packages. You can +add "static information" (news item that are meant to stay available +indefinitely) and news items in the "latest news" section. +

+Static news can be used to indicate: + +the availability of a project hosted on alioth.debian.org for co-maintaining the package +a link to the upstream website +a link to the upstream bugtracker +the existence of an IRC channel dedicated to the software +any other available resource that could be useful in the maintenance of the package + +Usual news item may be used to announce that: + +beta packages are available for test +final packages are expected for next week +the packaging is about to be redone from scratch +backports are available +the maintainer is on vacation (if he wishes to publish this information) +a NMU is being worked on +something important will affect the package + +

+Both kind of news are generated in a similar manner: you just have to send a mail +either to pts-static-news@qa.debian.org or to +pts-news@qa.debian.org. The mail should indicate which package is +concerned by the news by giving the name of the source package in a +X-PTS-Package mail header or in a Package pseudo-header (like the +BTS reports). If an URL is available in the X-PTS-Url mail header or in +the Url pseudo-header, then the result is a link to that URL instead +of a complete news item. +

+Some examples of valid mails used to generate news item in the PTS are following. The first one +adds a link to the cvsweb interface of debian-cd in the "Static information" section. + +From: Raphael Hertzog <hertzog@debian.org> +To: pts-static-news@qa.debian.org +Subject: Browse debian-cd CVS repository with cvsweb + +Package: debian-cd +Url: http://cvs.debian.org/debian-cd/ + +The second one is an announce sent to a mailing list which is also sent +to the PTS so that it is published on the PTS web page of the package. Note the +use of the BCC field to avoid answers sent to the PTS by mistake ... + +From: Raphael Hertzog <hertzog@debian.org> +To: debian-gtk-gnome@lists.debian.org +Bcc: pts-news@qa.debian.org +Subject: Galeon 2.0 backported for woody +X-PTS-Package: galeon + +Hello gnomers ! + +I'm glad to announce that galeon has been backported for woody. You'll find +everything here: +... + +

+Think twice before adding a news to the PTS because you won't be able to +remove it later and you wan't be able to edit it either. The only thing that you +can do is send a second news that will deprecate the information contained in +the first news. + Developer's packages overview

A QA (quality assurance) web portal is available at 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 @@ -1427,7 +1545,7 @@ packages.

The debian/changelog file conforms to a certain structure, with a number of different fields. One field of note, the -distribution, is described in . More +distribution, is described in . More information about the structure of this file can be found in the Debian Policy section titled "debian/changelog".

@@ -1444,11 +1562,12 @@ contains a new upstream version of the software looks like this: There are tools to help you create entries and finalize the changelog for release — see and . +

+See also . - - Checking the package prior to upload -

+ Testing the package +

Before you upload your package, you should do basic testing on it. At a minimum, you should try the following activities (you'll need to have an older version of the same Debian package around): @@ -1471,6 +1590,9 @@ to emit errors (they will start with E).

For more information on lintian, see . +Optionally run to analyze changes from an older version, +if one exists. + Downgrade the package to the previous version (if one exists) — this tests the postrm and prerm scripts. @@ -1478,70 +1600,74 @@ Remove the package, then reinstall it. - Generating the changes file -

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

-&control-file-fields; -

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

+ Layout of the source package +

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

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

+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 included in the .changes file. Subsequently, this very same tar file should be used to build the new diffs and .dsc files, and will not need to be re-uploaded. -

+

By default, dpkg-genchanges and dpkg-buildpackage will include the original source tar file if and only if the Debian revision part of the source version number is 0 or 1, indicating a new upstream version. This behavior may be modified by using -sa to always include it or -sd to always leave it out. -

+

If no original source is included in the upload, the original source tar-file used by dpkg-source when constructing the .dsc file and diff to be uploaded must be byte-for-byte identical with the one already in the archive. - 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. -

+ Picking a distribution +

+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 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. +distribution with anything else (see ). - - Uploading to stable -

+ Uploads to stable +

Uploading to stable means that the package will be placed into the stable-proposed-updates directory of the Debian archive for further testing before it is actually included in stable. -

+

Extra care should be taken when uploading to stable. Basically, a package should only be uploaded to stable if one of the following happens: @@ -1550,13 +1676,13 @@ package should only be uploaded to stable if one of the following happens: the package becomes uninstallable a released architecture lacks the package -

+

It is discouraged to change anything else in the package that isn't important, because even trivial fixes can cause bugs later on. Uploading new upstream versions to fix security problems is deprecated; applying the specific patch from the new upstream version to the old one ("back-porting" the patch) is the right thing to do in most cases. -

+

Packages uploaded to stable need to be compiled on systems running stable, so that their dependencies are limited to the libraries (and other packages) available in stable; for example, a package @@ -1564,7 +1690,7 @@ uploaded to stable that depends on a library package that only exists in unstable will be rejected. Making changes to dependencies of other packages (by messing with Provides or shlibs files), possibly making those other packages uninstallable, is strongly discouraged. -

+

The Release Team (which can be reached at &email-debian-release;) will regularly evaluate the uploads in stable-proposed-updates and decide if your package can be included in stable. Please be clear (and @@ -1572,34 +1698,37 @@ 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 -

+ Uploads 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 scripts when he wants to freeze the distribution. In that case, you may want to upload to testing-proposed-updates to provide fixed packages during the freeze. -

+

Keep in mind that packages uploaded there are not automatically processed, they have to go through the hands of the release manager. So you'd better have a good reason to upload there. In order to know what a good reason is in the release manager's eyes, you should read the instructions that he regularly gives on &email-debian-devel-announce;. -

+

You should not upload to testing-proposed-updates when you can update your packages through unstable. If you can't (for example because you have a 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 + Uploading a package + + Uploading to ftp-master

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

+Please note that you should transfer the changes file last. Otherwise, your upload may be rejected because the archive maintenance software will parse the changes file and see that not all files have been uploaded. If you don't want to bother with transferring @@ -1627,10 +1756,12 @@ process of uploading packages into Debian.

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

Note that dput can do this for you automatically. - Uploading to non-US + Uploading to non-US

As discussed above, export controlled software should not be uploaded to ftp-master. Instead, upload the package to @@ -1674,7 +1805,7 @@ advice. Again, it is strongly recommended that U.S. citizens and residents consult a lawyer before doing uploads to non-US. - Uploads via chiark + Uploads via chiark

If you have a slow network connection to ftp-master, there are alternatives. One is to upload files to Incoming via a @@ -1691,7 +1822,7 @@ The program dupload comes with support for uploading to program for details. - Uploads via erlangen + Uploads via erlangen

Another upload queue is available in Germany: just upload the files via anonymous FTP to . @@ -1722,7 +1853,7 @@ The program dupload comes with support for uploading to the program for details. - Other upload queues + Other upload queues

Another upload queue is available which is based in the US, and is a good backup when there are problems reaching ftp-master. You can @@ -1733,26 +1864,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

@@ -1774,16 +1885,19 @@ checking if any bugs you meant to close didn't get triggered. 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. +

+Note also that if you upload via queues, the queue daemon software will +also send you a notification by email. - 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 be placed in the archive, nor its priority. In order to retain the overall integrity of the archive, it is the archive maintainers who have control over these fields. The values in the debian/control file are actually just hints. -

+

The archive maintainers keep track of the canonical sections and priorities for packages in the override file. If there is a disparity between the override file and the package's fields @@ -1792,567 +1906,453 @@ email noting the divergence when the package is installed into the archive. You can either correct your debian/control file for your next upload, or else you may wish to make a change in the override file. -

+

To alter the actual section that a package is put in, you need to first make sure that the debian/control in your package is accurate. Next, send an email &email-override; or submit a bug against ftp.debian.org requesting that the section 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;. - - +name="dpkg-scanpackages" section="8"> and +. +

+Note also that the term "section" is used for the separation of packages +according to their licensing, e.g. main, contrib and +non-free. This is described in another section, . - 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. + Handling bugs

-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. +Every developer has to be able to work with the Debian . This includes knowing how to file bug +reports properly (see ), how to update them and +reorder them, and how to process and close them.

-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. - - - Who can do an NMU +The bug tracking system's features interesting to developers are described +in the . +This includes closing bugs, sending followup messages, assigning severities, +tags, marking bugs as forwarded and other issues.

-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. +Operations such as reassigning bugs to other packages, merging separate +bug reports about the same issue, or reopening bugs when they are +prematurely closed, are handled using the so-called control mail server. +All of the commands available in this server are described in the +. - - 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-host;). If you're writing a new +mail and you don't remember the submitter email address, you can +use the 123-submitter@&bugs-host; 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-host;).

- - -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-host;. 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 + Bug housekeeping

-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. +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 . + + When bugs are closed by new uploads +

+As bugs and problems are fixed your packages, it is your +responsibility as the package maintainer to close the bug. However, +you should not close the bug until the package which fixes the bug has +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. +

+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: - 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'. + +acme-cannon (3.1415) unstable; urgency=low + * Frobbed with options (closes: Bug#98339) + * Added safety to prevent operator dismemberment, closes: bug#98765, + bug#98713, #98714. + * Added man page. Closes: #98725. + - - 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 +Technically speaking, the following Perl regular expression describes +how bug closing changelogs are identified: - * Non-maintainer upload + /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig - - 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. +We prefer the closes: #XXX syntax, as it is the +most concise entry and the easiest to integrate with the text of the +changelog. +

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

+Bear in mind that it is not obligatory to close bugs using the +changelog as described above. If you simply want to close bugs that +don't have anything to do with an upload you made, do it by emailing +an explanation to XXX-done@&bugs-host;. Do +not close bugs in the changelog entry of a version if +the changes in that version of the package doesn't have any bearing on +the bug.

-In addition, the normal maintainer should always retain the -entry in the changelog file documenting the non-maintainer upload. +For general information on how to write your changelog entries, see +. - 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. + 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. - Acknowledging an NMU -

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

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

-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. + Any fixed packages that you have prepared yourself (send only + the .diff.gz and .dsc files) - - -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. - + Any information needed for the advisory (see ) + - 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. + 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: - - 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''. + + 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. - - 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. + 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. + - -

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

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

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

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

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

-Descriptions of several porting tools can be found in .

- + + 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 + - - 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. - + + 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, see ). +

+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. + + 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). + + 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 + ). + + + 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 @@ -2511,420 +2511,556 @@ 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 -

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

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

-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 + Being kind to porters

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

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

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

-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 . - + +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 (see ). +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 ). +

+If you can't set up a proper chroot, dpkg-depcheck may be +of assistance (see ). +

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

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

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

+Descriptions of several porting tools can be found in .

+ - - 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). + + 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. + -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! + 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. - 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. + 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. - 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). + 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. - 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 - ). + 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 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. - 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. - - When bugs are closed by new uploads + How to do a source 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. +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 .

-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: +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. - -acme-cannon (3.1415) unstable; urgency=low - * Frobbed with options (closes: Bug#98339) - * Added safety to prevent operator dismemberment, closes: bug#98765, - bug#98713, #98714. - * Added man page. Closes: #98725. - + 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'. + -Technically speaking, the following Perl regular expression is what is -used: + + 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 - /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig + * Non-maintainer upload -The author prefers the closes: #XXX syntax, as -one of the most concise and easiest to integrate with the text of the -changelog. + + 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 , follow the other +prescriptions in . +

+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. + + Acknowledging an NMU

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

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

+ +

+ + @@ -3034,22 +3170,22 @@ documentation and examples (in /usr/share/doc/dpatch). Multiple binary packages

A single source package will often build several binary packages, -either to provide several flavors of the same software (examples are -the vim-* packages) or to make several small +either to provide several flavors of the same software (e.g., +the vim source package) or to make several small packages instead of a big one (e.g., if the user can install only the subset she needs, and thus save some disk space).

The second case can be easily managed in debian/rules. You just need to move the appropriate files from the build directory into the package's temporary trees. You can do this using -install (vanilla approach) or dh_install -(from debhelper). Be sure to check the different +install or dh_install +from debhelper. Be sure to check the different permutations of the various packages, ensuring that you have the inter-package dependencies set right in debian/control.

The first case is a bit more difficult since it involves multiple -recompiles of the same software but with different configure -options. The vim is an example of how to manage +recompiles of the same software but with different configuration +options. The vim source package is an example of how to manage this using an hand-crafted debian/rules file. + + + Best practices for maintainer scripts

Maintainer scripts include the files debian/postinst, @@ -3114,76 +3542,11 @@ 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. - - - - Best practices for debian/control -

-The following practices supplement the .

- - - Writing useful descriptions -

-The description of the package (as defined by the corresponding field -in the control file) is the primary information available -to the user about a package before they install it. It should provide -all the required information to let the user decide whether to install -the package. -

-For consistency and aesthetics, you should capitalize the first letter -of the Synopsis. Don't put a full stop (period) at the end. The -description itself should consist of full sentences. -

-Since the first user impression is based on the description, be -careful to avoid spelling and grammar mistakes. Ensure that you -spell-check it. ispell has a special -g option -for debian/control files: - -ispell -d american -g debian/control - -If you want someone to proofread the description that you -intend to use you may ask on &email-debian-l10n-english;. - - - - Upstream home page -

-We recommend that you add the URL for the package's home page to the -package description in debian/control. This information -should be added at the -end of description, using the following format: - - . - Homepage: http://some-project.some-place.org/ - -Note the spaces prepending the line, which serves to break the lines -correctly. To see an example of how this displays, see . -

-If there is no home page for the software, this should naturally be -left empty. -

-Note that we expect this field will eventually be replaced by a proper -debian/control field understood by dpkg and -&packages-host;. If you don't want to bother migrating the -home page from the description to this field, you should probably wait -until that is available.

- - - Configuration management with debconf -

Debconf is a configuration management system which can be used by all the various packaging scripts @@ -3351,7 +3714,6 @@ Lisp packages should register themselves with &file-lisp-controller;. - + + Architecture-independent data +

+It is not uncommon to have a large amount of architecture-independent +data packaged with a program. For example, audio files, a collection +of icons, wallpaper patterns, or other graphic files. If the size of +this data is negligible compared to the size of the rest of the +package, it's probably best to keep it all in a single package. +

+However, if the size of the data is considerable, consider splitting +it out into a separate, architecture-independent package ("_all.deb"). +By doing this, you avoid needless duplication of the same data into +eleven or more .debs, one per each architecture. While this +adds some extra overhead into the Packages files, it +saves a lot of disk space on Debian mirrors. Separating out +architecture-independent data also reduces processing time of +lintian or linda (see ) +when run over the entire Debian archive. + + + @@ -3384,21 +3767,39 @@ members in choosing what they want to work on and in choosing the most critical thing to spend their time on. - Bug reporting + Bug reporting

We encourage you to file bugs as you find them in Debian packages. In fact, Debian developers are often the first line testers. Finding and -reporting bugs in other developer's packages improves the quality of +reporting bugs in other developers' packages improves the quality of Debian.

+Read the in the Debian . +

Try to submit the bug from a normal user account at which you are -likely to receive mail. Do not submit bugs as root. +likely to receive mail, so that people can reach you if they need +further information about the bug. Do not submit bugs as root. +

+You can use a tool like to +submit bugs. It can automate and generally ease the process. +

+Make sure the bug is not already filed against a package. +Each package has a bug list easily reachable at +http://&bugs-host;/packagename +Utilities like can also +provide you with this information (and reportbug +will usually invoke querybts before sending, too). +

+Try to direct your bugs to the proper location. When for example +your bug is about a package that overwrites files from another package, +check the bug lists for both of those packages in order to +avoid filing duplicate bug reports.

-Make sure the bug is not already filed against a package. Try to do a -good job reporting a bug and redirecting it to the proper location. For extra credit, you can go through other packages, merging bugs -which are reported more than once, or setting bug severities to -`fixed' when they have already been fixed. Note that when you are +which are reported more than once, or tagging bugs `fixed' +when they have already been fixed. Note that when you are neither the bug submitter nor the package maintainer, you should not actually close the bug (unless you secure permission from the maintainer). @@ -3407,7 +3808,7 @@ From time to time you may want to check what has been going on with the bug reports that you submitted. Take this opportunity to close those that you can't reproduce anymore. To find out all the bugs you submitted, you just have to visit -http://&bugs-host;/from:<your-email-addr>. +http://&bugs-host;/from:<your-email-addr>. Reporting lots of bugs at once

@@ -3426,7 +3827,7 @@ will help prevent a situation in which several maintainers start filing the same bug report simultaneously.

Note that when sending lots of bugs on the same subject, you should -send the bug report to maintonly@bugs.debian.org so +send the bug report to maintonly@&bugs-host; so that the bug report is not forwarded to the bug distribution mailing list. @@ -3625,7 +4026,7 @@ with debsign -m"FULLNAME email-addr" changes before uploading it to the incoming directory.

The Maintainer field of the control file and the -changelog should list the person who did the packaging, i.e. the +changelog should list the person who did the packaging, i.e., the sponsoree. The sponsoree will therefore get all the BTS mail about the package.

@@ -3734,7 +4135,7 @@ You should periodically get the newest lintian from option provides detailed explanations of what each error or warning means, what is its basis in Policy, and commonly how you can fix the problem.

-Refer to for more information on how and when +Refer to for more information on how and when to use Lintian.

You can also see a summary of all problems reported by Lintian on your @@ -3750,8 +4151,33 @@ packages at . Those reports contain the latest lintian but has a different set of checks. Its written in Python rather than Perl.

+ + + debdiff +

+debdiff (from the devscripts package, ) +compares file lists and control files of two packages. It is a simple +regression test, as it will help you notice if the number of binary +packages has changed since the last upload, or if something's changed +in the control file. Of course, some of the changes it reports will be +all right, but it can help you prevent various accidents. +

+You can run it over a pair of binary packages: + +debdiff package_1-1_arch.deb package_2-1_arch.deb + +

+Or even a pair of changes files: + +debdiff package_1-1_arch.changes package_2-1_arch.changes + +

+For more information please see . + + + Helpers for debian/rules

@@ -4000,6 +4426,30 @@ directory of your package. For instance, when editing debian/changelog, there are handy functions for finalizing a version and listing the package's current bugs.

 + + + dpkg-depcheck +

+dpkg-depcheck (from the devscripts +package, ) +runs a command under strace to determine all the packages that +were used by the said command. +

+For Debian packages, this is useful when you have to compose a +Build-Depends line for your new package: running the build +process through dpkg-depcheck will provide you with a +good first approximation of the build-dependencies. For example: + +dpkg-depcheck -b debian/rules build + +

+dpkg-depcheck can also be used to check for run-time +dependencies, especially if your package uses exec(2) to run other +programs. +

+For more information please see . + + @@ -4066,6 +4516,9 @@ it.