X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=ba883c6d21fb2079c1afdafc875fa83f53ec4a2a;hp=8d5bbf8118080faf7accad042581e6eecb8149ad;hb=e4285cf6103cd328a1f5485f3e6db2a88a2605a2;hpb=7f3396f535c65eaf2bb243eaf2587da737ce323e diff --git a/developers-reference.sgml b/developers-reference.sgml index 8d5bbf8..ba883c6 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 availabe in the unstable +distribution, you can close the bug. This can be done automatically, +read . + When bugs are closed by new uploads @@ -2458,6 +2569,159 @@ 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 functionnalities. The package +hello-dbs is a simple example that demonstrates how to +use dbs. +

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

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

+ &FIXME; Denis Barbier is going to write it. + + + + 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 subpolicies 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 in the intent 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 manpage. +It is something that you must have read if you decide to use debconf. + + + Miscellaenous advice @@ -2855,16 +3119,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 +3169,7 @@ thing). alien dpkg-repack grep-dctrl - pbuilder --> +-->