X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=ab5b26f621930ec37d376aadffc170d095cc06e4;hb=e43a8d7567590ae3fc131fd9620dd88d8f2ee50e;hp=1a90106b878eb407169ca059c4b12efdf9047ef7;hpb=34de8a86363cbd42d2b922ad28349830a0255f1e;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 1a90106..ab5b26f 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - +

The Package Tracking System (PTS) is basically a tool to track by mail the activity of a source package. You just have to subscribe @@ -1279,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 @@ -1430,7 +1465,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".

@@ -1447,18 +1482,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 . - - - Package uploads -

-When a package is uploaded to the Debian archive, it must be accompanied by -a .changes control file, which gives directions to the archive -maintenance software for its handling. This is generated by -dpkg-genchanges during the normal package build process. +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): @@ -1481,6 +1510,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. @@ -1488,74 +1520,74 @@ Remove the package, then reinstall it. - Layout of the source files -

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

+ 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', 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: @@ -1564,13 +1596,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 @@ -1578,7 +1610,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 @@ -1586,35 +1618,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 a package - Uploading to ftp-master + 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 @@ -1642,10 +1676,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 @@ -1689,7 +1725,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 @@ -1706,7 +1742,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 . @@ -1737,7 +1773,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 @@ -1769,16 +1805,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. - Determining section and priority of a package -

+ 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 @@ -1787,14 +1826,14 @@ 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 and . @@ -1804,15 +1843,25 @@ according to their licensing, e.g. main, contrib and non-free. This is described in another section, . - Handling package bugs + Handling bugs +

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

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

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

If you want to be a good maintainer, you should periodically check the for your @@ -1840,16 +1889,16 @@ maintainer address.

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 +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.debian.org email to +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.debian.org). +123@&bugs-host;).

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 +123-done@&bugs-host;. If you're fixing a bug by changing and uploading the package, you can automate bug closing as described in .

@@ -1866,7 +1915,7 @@ 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 +control server documentation">. This section contains some guidelines for managing your own bugs, based on the collective Debian developer experience.

@@ -1943,15 +1992,15 @@ read . When bugs are closed by new uploads

-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, +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 +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: @@ -1964,30 +2013,35 @@ acme-cannon (3.1415) unstable; urgency=low * Added man page. Closes: #98725. -Technically speaking, the following Perl regular expression is what is -used: +Technically speaking, the following Perl regular expression describes +how bug closing changelogs are identified: /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig -The author prefers the closes: #XXX syntax, as -one of the most concise and easiest to integrate with the text of the +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 one in the changelog file, -don't hesitate to undo any damage the error caused. To reopen wrongly closed -bugs, send an reopen XXX command in the bug tracking -system's control bot. To close any remaining bugs that were fixed by your -upload, email the .changes file to -XXX-done@bugs.debian.org, where XXX is your -bug number. -

-Bear in mind that it is not obligatory to close bugs using the changelog -like described above -- if you simply want to close bugs that don't have -anything to do with an upload of yours, do it simply by emailing an -explanation to XXX-done@bugs.debian.org. -Do not close bugs in the changelog entry of a version -if the said version of the package doesn't have anything to do with the bug. +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. +

+For general information on how to write your changelog entries, see +. + Handling security-related bugs

@@ -2138,9 +2192,9 @@ 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). - +and debdiff from devscripts are useful +tools for this, see ). +

When packaging the fix, keep the following points in mind: @@ -2419,13 +2473,17 @@ 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 +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. +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. @@ -2723,7 +2781,7 @@ 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. ). +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. @@ -2854,9 +2912,8 @@ entry in the changelog file documenting the non-maintainer upload. Building source NMUs

Source NMU packages are built normally. Pick a distribution using the -same rules as found in . Just as described in -, a normal changes file, etc., will be built. In -fact, all the prescriptions from apply. +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 @@ -3033,22 +3090,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, @@ -3113,76 +3462,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 @@ -3366,26 +3650,29 @@ Lisp packages should register themselves with sympa may be an example package --> - Architecture-independent data -

- It is not uncommon to have a large amount of architecture-independent - data packaged with a program. For example, collection of icons, - wallpapers or other graphic files, or audio files. If the size of - this data is negligible compared to the size of the remainder of the - package, you can keep it all in the same 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 per each architecture. While - this adds some extra overhead into the Packages files, it can save a - lot of disk space on Debian mirrors, and it also reduces processing - time of Lintian or Linda when run over the entire Debian archive. - - + + 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. + + + Beyond Packaging @@ -3400,21 +3687,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). @@ -3423,7 +3728,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

@@ -3442,7 +3747,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. @@ -3641,7 +3946,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.

@@ -3750,7 +4055,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 @@ -3766,8 +4071,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

@@ -4016,6 +4346,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 . + + @@ -4082,6 +4436,9 @@ it.