X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=dea325efb3d5bce8ef4e4639b8066c435aa5b040;hb=e22ed8f4833f5a95c8b09504c2b19e93709c1120;hp=190b8e65a55e7b3eb1c9f247d043e62bfcd91981;hpb=1256553e5fab7d9306837f6a29e4b87e448a0e15;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 190b8e6..dea325e 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + +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. Uploading to stable

Uploading to stable means that the package will be placed into the -proposed-updates directory of the Debian archive for further +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 @@ -1501,13 +1545,29 @@ 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 proposed-updates and decide if +regularly evaluate the uploads in stable-proposed-updates and decide if your package can be included in stable. Please be clear (and verbose, if necessary) in your changelog entries for uploads to stable, because otherwise the package won't be considered for inclusion. - + Uploading to testing-proposed-updates +

+The testing distribution is fed with packages from unstable according to the rules +explained in . However, the release manager may stop the testing +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 @@ -1549,7 +1609,7 @@ maintenance software will process it by running dinstall on your changes file: dinstall -n foo.changes. Note that dput can do this for you automatically. - Uploading to non-US (pandora) + Uploading to non-US

As discussed above, export controlled software should not be uploaded to ftp-master. Instead, upload the package to @@ -1795,29 +1855,25 @@ 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, a fixed package should be uploaded -as soon as possible. In this case, the Debian security officers get in -contact with the package maintainer to make sure a fixed package is -uploaded within a reasonable time (less than 48 hours). If the package -maintainer cannot provide a fixed package fast enough or if he/she -cannot be reached in time, a security officer may upload a fixed -package (i.e., do a source NMU). +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. +id="nmu-guidelines"> need to be followed. Special exceptions are made +for .

-Bug fixes to unstable by non-maintainers are also acceptable, but only -as a last resort or with permission. The following protocol should -be respected to do an NMU: +Uploading bug fixes to unstable by non-maintainers should only be done +by following this protocol:

-Make sure that the package's bug is in the Debian Bug Tracking System -(BTS). If not, submit a bug. +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 @@ -1838,7 +1894,15 @@ 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. How to do a source NMU

@@ -1960,7 +2024,7 @@ changes file. Acknowledging an NMU

-If one of your packages has been NMUed, you have to incorporate the +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 @@ -2250,7 +2314,11 @@ version control system, such as CVS or

Add the co-maintainer's correct maintainer name and address to the Uploaders field in the global part of the -debian/control file.

+debian/control file. + +Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org> + +

@@ -2345,10 +2413,21 @@ it. In this case, you need to follow a two-step process. First, set your debian/control file to replace and conflict with the obsolete name of the package (see the for details). Once you've uploaded -that package, and the package has moved into the archive, file a bug +the package and the package has moved into the archive, file a bug against ftp.debian.org asking to remove the package with the obsolete name. Do not forget to properly reassign the package's bugs at the same time. +

+At other times, you may make a mistake in constructing your package and +wish to replace it. The only way to do this is to increase the version +number and upload a new version. The old version will be expired in +the usual manner. Note that this applies to each part of your package, +including the sources: if you wish to replace the upstream source tarball +of your package, you will need to upload it with a different version. An +easy possibility is to replace foo_1.00.orig.tar.gz with +foo_1.00+0.orig.tar.gz. This restriction gives each file +on the ftp site a unique name, which helps to ensure consistency across the +mirror network. Orphaning a package

@@ -2484,9 +2563,8 @@ 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). - +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 @@ -2531,6 +2609,209 @@ distribution, you can close the bug. This can be done automatically, read . + Handling security-related bugs +

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

+When you become aware of a security-related bug in a Debian package, +whether or not you are the maintainer, collect pertinent information +about the problem, and promptly contact the security team at +&email-security-team;. +Useful information includes, for example: + + + What versions of the package are known to be affected by the + bug. + + The nature of the exposure (root compromise, user compromise, + remote/local attack) + + The nature of the fix, if any is available (patches are + especially helpful) + + + Confidentiality +

+Unlike most other activities within Debian, information about security +issues must sometimes be kept private for a time. Whether this is the +case depends on the nature of the problem and corresponding fix, and +whether it is already a matter of public knowledge. +

+There are a few ways a developer can learn of a security problem: + + + he notices it on a public forum (mailing list, web site, etc.) + someone files a bug report + someone informs him via private email + + + In the first two cases, the information is public and it is important + to have a fix as soon as possible. In the last case, however, it + might not be public information. In that case there are a few + possible options for dealing with the problem: + + + if it is a trivial problem (like insecure temporary files) + there is no need to keep the problem a secret and a fix should be + made and released. + + if the problem is severe (remotely exploitable, possibility to + gain root privileges) it is preferable to share the information with + other vendors and coordinate a release. The security team keeps + contacts with the various organizations and individuals and can take + care of that. + + +

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

+Please note that if secrecy is needed you can also not upload a fix to +unstable (or anywhere else), since the changelog and diff information +for unstable is public. + +

+There are two reasons for releasing information even though secrecy is +requested: the problem has been known for a while, or that the problem +or exploit has become public. + + Security Advisories +

+Security advisories are only issued for the current, released stable +distribution, not for testing or unstable. When released, advisories +are sent to the &email-debian-security-announce; +mailing list and posted on . +Security advisories are written and posted by the security +team. However they certainly do not mind if a maintainer can supply +some of the information for them, or write part of the +text. Information that should be in an advisory includes: + + + A description of the problem and its scope, including: + + The type of problem (privilege escalation, denial of + service, etc.) + How it can be exploited + Whether it is remotely or locally exploitable + How the problem was fixed + + Version numbers of affected packages + Version numbers of fixed packages + Information on where to obtain the updated packages + + + + 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. + +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. 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. + + Always build with full source (use the -sa option + for dpkg-buildpackage). + + 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. +

+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

@@ -2616,8 +2897,8 @@ almost always automatically done by a debhelper script. Furthermore it offers enough flexibility to be able to use it in conjunction with some hand crafted shell invocations within the rules file.

-You can however decide to not use any helper script, and still write -some very good rules file. Many examples are available +You can however decide to not use any helper script and still write +excellent rules file. Many examples are available at . + + Packages using + autoconf/automake +

+Some very good packaging practices for packages using +autoconf and/or automake have been +synthesized in &file-bpp-autotools;. You're strongly encouraged to +read this file and to follow the given recommendations. + + Libraries

Libraries are always difficult to package for various reasons. The policy imposes many constraints to ease their maintenance and to make sure upgrades are as simple as possible when a new upstream version comes out. -A breakage in a library can result in dozens of dependent packages to -break... +A breakage in a library can result in dozens of dependent packages +breaking.

Good practices for library packaging have been grouped in . @@ -2726,7 +3017,7 @@ Several subsets of packages have special sub-policies and corresponding packaging rules and practices: -Perl related packages have a , +Perl related packages have a , some examples of packages following that policy are libdbd-pg-perl (binary perl module) or libmldbm-perl (arch independent perl module). @@ -2740,7 +3031,7 @@ name="emacs policy">. Java related packages have their . -Ocaml related packages have their ocaml policy: &file-ocaml-policy; (in +Ocaml related packages have their Ocaml policy: &file-ocaml-policy; (in the ocaml package). A good example is the camlzip source package. @@ -2748,15 +3039,18 @@ source package. Configuration management - The wise use of debconf -

-Debconf is a configuration management system, it is used by all the -various packaging scripts (postinst mainly) to request feedback from the -user concerning how to configure the package. Direct user interactions -must now be avoided in favor of debconf interaction. This will enable -non-interactive installations in the future. + + Proper use of debconf +

+Debconf is a configuration management system which +can be used by all the various packaging scripts +(postinst mainly) to request feedback from the user +concerning how to configure the package. Direct user interactions must +now be avoided in favor of debconf +interaction. This will enable non-interactive installations in the +future.

-Debconf is a great tool but it is often badly used ... many common mistakes +Debconf is a great tool but it is often poorly used. Many common mistakes are listed in the man page. It is something that you must read if you decide to use debconf. @@ -2801,7 +3095,8 @@ that description, you should be careful to avoid English mistakes. Ensure that you spell check it. ispell has a special option (-g) for that: 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;. @@ -2814,7 +3109,7 @@ ways, often really critical ways, to contribute to Debian beyond simply creating and maintaining packages.

As a volunteer organization, Debian relies on the discretion of its -members in choosing what they want to work on, and choosing what is +members in choosing what they want to work on and in choosing the most critical thing to spend their time on. @@ -2866,6 +3161,8 @@ list. Quality Assurance effort + + Daily work

Even though there is a dedicated group of people for Quality Assurance, QA duties are not reserved solely for them. You can @@ -2875,7 +3172,36 @@ possible. If you do not find that possible, then you should consider orphaning some of your packages (see ). Alternatively, you may ask the help of other people in order to catch up the backlog of bugs that you have (you can ask -for help on &email-debian-qa; or &email-debian-devel;). +for help on &email-debian-qa; or &email-debian-devel;). At the same +time, you can look for co-maintainers (see ). + + Bug Squashing Parties +

+From time to time the QA group organizes bug squashing parties to get rid of +as many problems as possible. They are announced on &email-debian-devel-announce; +and the announce explains what area will be focused on during the party: +usually they focus on release critical bugs but it may happen that they +decide to help finish a major upgrade going on (like a new perl version +which requires recompilation of all the binary modules). +

+The rules for non-maintainer uploads differ during the parties because +the announce of the party is considered like a prior notice for NMU. If +you have packages that may be affected by the party (because they have +release critical bugs for example), you should send an update to each of +the corresponding bug to explain their current status and what you expect +from the party. If you don't want an NMU, or if you're only interested in a +patch, or if you will deal yourself with the bug, please explain that in +the BTS. +

+People participating in the party have special rules for NMU, they can +NMU without prior notice if they upload their NMU to +DELAYED/3-day at least. All other NMU rules applies as usually, they +should send the patch of the NMU in the BTS (in one of the open bugs +fixed by the NMU or in a new bug tagged fixed). They should +also respect the maintainer's wishes if he expressed some. +

+If someone doesn't feel confident with an NMU, he should just send a patch +to the BTS. It's far better than a broken NMU. Dealing with unreachable maintainers

@@ -2956,7 +3282,7 @@ the package meets minimum Debian standards. That implies that you must build and test the package on your own system before uploading.

You can not simply upload a binary .deb from the sponsoree. In -theory, you should only ask only for the diff file, and the location of the +theory, you should only ask only for the diff file and the location of the original source tarball, and then you should download the source and apply the diff yourself. In practice, you may want to use the source package built by your sponsoree. In that case, you have to check that they haven't @@ -3127,7 +3453,7 @@ changes into the repository.

These utilities provide an infrastructure to facilitate the use of CVS by Debian maintainers. This allows one to keep separate CVS branches -of a package for stable, unstable, and possibly +of a package for stable, unstable and possibly experimental distributions, along with the other benefits of a version control system.