X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=3b1206feb930bff99b49e0076307e098b909c228;hp=82477545009ed4e5133e9658a13e33fd6fabe64c;hb=3ffcf7926a412ff96c64e52e5c8c887f24491c76;hpb=cdfe8d781e504566f443d9b05487e32f44f769bf diff --git a/developers-reference.sgml b/developers-reference.sgml index 8247754..3b1206f 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + + +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 @@ -2458,29 +2652,214 @@ faced during packaging. It also lists various advice collected on several mailing lists. By following them, you will make Debian's quality even better. + + Packaging tools and common cases + + Helper scripts +

+To help you in your packaging effort, you can use helper scripts. +The best scripts available are provided by debhelper. +With dh_make (package dh-make), you can +generate in a few seconds a package that is mostly ready. However that +apparent simplicity is hiding many things done by the helper scripts. +You have to know what is done by them, that's why you are strongly +encouraged to read the corresponding manual pages, starting with +debhelper(1). That's required because you'll have to +understand what is going on to be able to use them wisely and to +fix bugs in a pretty way. +

+debhelper is very useful because it lets you follow the latest Debian policy +without doing many modifications since the changes that can be automated are +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 +at . + + + + Package with multiple patches +

+Big packages tend to have many upstream bugs that you want to fix within +the Debian package. If you just correct the bug in the source, all the +fixes are directly integrated in the .diff.gz file and you +can't easily differentiate the various patches that you applied. It gets +very messy when you have to update the package to a new upstream version +which integrates some of the fixes (but not all). +

+The good solution is to keep separate patches within the +debian/patches directory and to apply them on the fly at +build time. The package dbs provides an +implementation of such a system, you just have to build-depend on dbs to +be able to use its functionalities. The package +hello-dbs is a simple example that demonstrates how to +use dbs. +

+Additionally, dbs provides facilities to create the patches and to keep +track of what they are for. + + 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 packages instead of a big one +(it's interesting if the user doesn't need all the packages and can thus +save some disk space). +

+The second case can be easily managed by dh_install (from +debhelper) to move files from the build directory to +the package's temporary trees. +

+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 this with an +hand crafted rules file. + + + Handling debconf translations +

+Like porters, translators have a difficult task. Since they work on many +packages, they cannot keep track of every change in packages in order to +be informed when a translated string is outdated. Fortunately +debconf can automatically report outdated translations, +if package maintainers follow some basic guidelines described below. +

+Translators can use debconf-getlang (package +debconf-utils) to write a templates.xx +file containing both English and localized fields (where xx is +the language code, may be followed by a country code). This file can be +put into the debian subdirectory without any change. +

+When building a binary package, debian/templates.xx files are +merged along with debian/templates to generate the +templates file contained in the binary package. This is +automatically done by dh_installdebconf (package +debhelper). If you do not use debhelper, you can +do the same with debconf-mergetemplate +(package debconf-utils). +

+When the package maintainer needs to update the templates file, they only +change debian/templates. When English strings in this file +and in debian/templates.xx differ, translators do know that +their translation is outdated. +

+Please see the page about + +at the Debian web site, it contains more detailed instructions, including a +full example. + + + + Specific packaging practices + + + + 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... +

+Good practices for library packaging have been grouped in +. + + Other specific packages +

+Several subsets of packages have special sub-policies and corresponding +packaging rules and practices: + + +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). + +Python related packages have their python policy: +&file-python-policy; (in the python package). + +Emacs related packages have the . + +Java related packages have their . + +Ocaml related packages have their ocaml policy: &file-ocaml-policy; (in +the ocaml package). A good example is the camlzip +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. +

+Debconf is a great tool but it is often badly used ... many common mistakes +are listed in the man page. +It is something that you must read if you decide to use debconf. + + + - Miscellaenous advice + Miscellaneous advice Writing useful descriptions

The description of the package (as defined by the corresponding field in the control file) is usually the first information -available to the user before he installs it. As such, it should +available to the user before they install it. As such, it should provide all the required information to let him decide whether to install the package.

For example, apart from the usual description that you adapt from the upstream README, you should include the URL of the -website if there's any. If the package is not yet considered stable +web site if there's any. If the package is not yet considered stable by the author, you may also want to warn the user that the package is not ready for production use.

+For consistency and for an aesthetic concern, you should capitalize the +first letter of the description. +

Last but not least, since the first user impression is based on -that description, you should be careful to avoid english +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 +ispell has a special option (-g) for that: +ispell -d american -g debian/control. + @@ -2520,12 +2899,12 @@ 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;/<your-email>@your-isp.com. +http://&bugs-host;/from:<your-email-addr>. Reporting lots of bugs at once

Reporting a great number of bugs for the same problem on a great -number of different packages &mdash i.e., more than 10 &mdash is a deprecated +number of different packages — i.e., more than 10 — is a deprecated practice. Take all possible steps to avoid submitting bulk bugs at all. For instance, if checking for the problem can be automated, add a new check to lintian so that an error or warning @@ -2566,8 +2945,8 @@ If you do not get a reply after a few weeks you should collect all useful information about this maintainer. Start by logging into the and doing a full search to check whether the maintainer is on vacation -and when he was last seen. Collect any important package names -he maintains and any Release Critical bugs filled against them. +and when they were last seen. Collect any important package names +they maintain and any Release Critical bugs filed against them.

Send all this information to &email-debian-qa;, in order to let the QA people do whatever is needed. @@ -2587,7 +2966,7 @@ email the maintainer, whatever their individual email address (or addresses) may be. Replace <package> with the name of a source or a binary package.

-You may also be interested by contacting the persons who are +You may also be interested in contacting the persons who are subscribed to a given source package via . You can do so by using the <package-name>@&pts-host; email address. @@ -2615,7 +2994,7 @@ id="&url-sponsors;">. New maintainers usually have certain difficulties creating Debian packages — this is quite understandable. That is why the sponsor is there, to check the package and verify that it is good enough for inclusion in Debian. -(Note that if the sponsored package is new, the FTP admins will also have to +(Note that if the sponsored package is new, the ftpmasters will also have to inspect it before letting it in.)

Sponsoring merely by signing the upload or just recompiling is @@ -2638,9 +3017,9 @@ 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 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 he hasn't -altered the upstream files in the .orig.tar.gz file that he's -providing. +built by your sponsoree. In that case, you have to check that they haven't +altered the upstream files in the .orig.tar.gz file that +they're providing.

Do not be afraid to write the sponsoree back and point out changes that need to be made. It often takes several rounds of back-and-forth @@ -2855,16 +3234,29 @@ depends. Or, you can test how your package behaves when installed into a bare base system. + + pbuilder +

+pbuilder constructs a chrooted system, and builds +a package inside the chroot. It is very useful to check that +a package's build-dependencies are correct, and to be sure that +unnecessary and wrong build dependencies will not exist in the +resulting package. + + devscripts

devscripts is a package containing a few wrappers -and tools which you may find helpful for maintaining your Debian +and tools which are very helpful for maintaining your Debian packages. Example scripts include debchange and dch, which manipulate your debian/changelog file from the command-line, and debuild, which is a -wrapper around dpkg-buildpackage. - +wrapper around dpkg-buildpackage. The bts +utility is also very helpful to update the state of bug reports on the +command line, as is uscan to watch for new upstream +versions of your packages. Check the devscripts(1) manual +page for a complete list of available scripts. @@ -2892,7 +3284,7 @@ thing). alien dpkg-repack grep-dctrl - pbuilder --> +-->