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=f56ecd4237747c0f5993d63cdd9209d981fe07f3;hb=491b29a243ffc0be9f99bb12ac22c65ada8f96c4;hpb=e63de6119053a4ac8892093cb8055bb1c86904f1 diff --git a/developers-reference.sgml b/developers-reference.sgml index f56ecd4..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, @@ -3146,82 +3542,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. -

-The following practices supplement the . -

-The synopsis line (the short description) should primarily be concise. -You may capitalize the first letter for aesthetics. It is customary to -make the synopsis an appositive clause (not a full sentence) in which -case there's no need to put a full stop (period) at the end. -

-The long description should, however, always 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 @@ -3405,168 +3730,27 @@ 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. - - - - - - Best practices for debian/changelog -

-The following practices supplement the .

- - - Writing useful changelog entries -

-The changelog entry for a package revision documents changes in that -revision, and only them. Concentrate on describing significant and -user-visible changes that were made since the last version. -

-Focus on what was changed — who, how and when are -usually less important. Having said that, remember to politely -attribute people who have provided notable help in making the package -(e.g., those who have sent in patches). + + Architecture-independent data

-There's no need to elaborate the trivial and obvious changes. You can -also aggregate several changes in one entry. On the other hand, don't -be overly terse if you have undertaken a major change. Be especially -clear if there are changes that affect the behaviour of the program. -For further explanations, use the README.Debian file. +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.

-Use common English so that the majority of readers can comprehend it. -Avoid abbreviations, "tech-speak" and jargon when explaining changes -that close bugs, especially for bugs filed by users that did not -strike you as particularly technically savvy. Be polite, don't swear. -

-It is sometimes desirable to prefix changelog entries with the names -of the files that were changed. However, there's no need to -explicitly list each and every last one of the changed files, -especially if the change was small or repetitive. You may use -wildcards. -

-When referring to bugs, don't assume anything. Say what the problem -was, how it was fixed, and append the "closes: #nnnnn" string. See - for more information. - - - - Common misconceptions about changelog entries -

-The changelog entries should not document generic -packaging issues ("Hey, if you're looking for foo.conf, it's in -/etc/blah/."), since administrators and users are supposed to be at -least remotely acquainted with how such things are generally arranged -on Debian systems. Do, however, mention if you change the location of -a configuration file. -

-The only bugs closed with a changelog entry should be those that are -actually fixed in the same package revision. Closing unrelated bugs -in the changelog is bad practice. See . -

-The changelog entries should not be used for random -discussion with bug reporters ("I don't see segfaults when starting -foo with option bar; send in more info"), general statements on life, -the universe and everything ("sorry this upload took me so long, but I -caught the flu"), or pleas for help ("the bug list on this package is -huge, please lend me a hand"). Such things usually won't be noticed -by their target audience, but may annoy people who wish to read -information about actual changes in the package. See for more information on how to use the bug -tracking system. -

-It is an old tradition to acknowledge bugs fixed in non-maintainer -uploads in the first changelog entry of the proper maintainer upload, -for instance, in a changelog entry like this: - - * Maintainer upload, closes: #42345, #44484, #42444. - -This will close the NMU bugs in "fixed" state when the package makes -it into the archive (and also the bug for the fact that an NMU was -done). It is also perfectly acceptable to close NMU-fixed bugs by -other means; see . -

-Changelogs shouldn't include general statements on life, the universe -and everything ("sorry this upload took me so long, but I caught the -flu"). Exceptions can be made if the comment is funny ;-) Obviously, -this is subjective, so it's likely best if it's kept out of technical -documentation such as changelogs. - - - - Common errors in changelog entries -

-The following examples demonstrate some common errors or example of -bad style in changelog entries. - -

- - * Fixed all outstanding bugs. - -This doesn't tell readers anything too useful, obviously. - -

- - * Applied patch from Jane Random. - -What was the patch about? - -

- - * Late night install target overhaul. - -Overhaul which accomplished what? Is the mention of late night -supposed to remind us that we shouldn't trust that code? - -

- - * Fix vsync FU w/ ancient CRTs. - -Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, -a curse word!) was actually about, or how it was fixed. - -

- - * This is not a bug, closes: #nnnnnn. - -First of all, there's absolutely no need to upload the package to -convey this information; instead, use the bug tracking system. -Secondly, there's no explanation as to why the report is not a bug. - -

- - * Has been fixed for ages, but I forgot to close; closes: #54321. - -If for some reason you didn't mention the bug number in a previous changelog -entry, there's no problem, just close the bug normally in the BTS. There's -no need to touch the changelog file, presuming the description of the fix is -already in (this applies to the fixes by the upstream authors/maintainers as -well, you don't have to track bugs that they fixed ages ago in your -changelog). - -

- - * Closes: #12345, #12346, #15432 - -Where's the description? If you can't think of a descriptive message, -start by inserting the title of each different bug. +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. + @@ -3583,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). @@ -3606,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

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