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=c2f263c8456a630e64432f1ed65b7566aaecf729;hb=491b29a243ffc0be9f99bb12ac22c65ada8f96c4;hpb=8d420f7f01377b784a50c9fb97ae90814892108f diff --git a/developers-reference.sgml b/developers-reference.sgml index c2f263c..ea0d883 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + + + Best practices for maintainer scripts +

+Maintainer scripts include the files debian/postinst, +debian/preinst, debian/prerm and +debian/postrm. These scripts take care of any package +installation or deinstallation setup which isn't handled merely by the +creation or removal of files and directories. The following +instructions supplement the . +

+Maintainer scripts must be idempotent. That means that you need to +make sure nothing bad will happen if the script is called twice where +it would usually be called once. +

+Standard input and output may be redirected (e.g. into pipes) for +logging purposes, so don't rely on them being a tty. +

+All prompting or interactive configuration should be kept to a +minimum. When it is necessary, you should use the +debconf package for the interface. Remember that +prompting in any case can only be in the configure stage of +the postinst script. +

+Keep the maintainer scripts as simple as possible. We suggest you use +pure POSIX shell scripts. Remember, if you do need any bash features, +the maintainer script must have a bash sh-bang line. POSIX shell or +Bash are preferred to Perl, since they enable +debhelper to easily add bits to the scripts. +

+If you change your maintainer scripts, be sure to test package +removal, double installation, and purging. Be sure that a purged +package is completely gone, that is, it must remove any files created, +directly or indirectly, in any maintainer script. +

+If you need to check for the existence of a command, you should use +something like +if [ -x /usr/sbin/install-docs ]; then ... + +If you don't wish to hard-code the path of the command in your +maintainer script, the following POSIX-compliant shell function may +help: + +&example-pathfind; + +You can use this function to search $PATH for a command name, +passed as an argument. It returns true (zero) if the command was +found, and false if not. This is really the most portable way, since +command -v, type, and which are not +POSIX. +

+While which is an acceptable alternative, since +it is from the required debianutils package, it's +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. + + + Configuration management with debconf -

Debconf is a configuration management system which can be used by all the various packaging scripts @@ -3553,9 +3740,9 @@ 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 per each architecture. While this +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 @@ -3580,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). @@ -3603,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

@@ -4311,6 +4516,9 @@ it.