X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=9fc6275d69691e3bdc351eba3d1c1596a224865c;hb=605f72913c9637e4f12c766da6757816953a9718;hp=dcaced2e7dd34165a0c6d573556d80b8ad9112ca;hpb=4429914d13bcd922d5f29aae420b19697f7ffe1b;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index dcaced2..9fc6275 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, @@ -3136,82 +3459,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 @@ -3395,154 +3647,28 @@ 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. + - - 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 changes you did since -the last version that are worth mentioning. -

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

-There's no need to elaborate the trivial and obvious changes. You can also -aggregate several such changes in one entry. However, 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 -- and for further -explanations, use the README.Debian file. -

-Use common English language, one which the majority of viewers can -understand. Avoid abbreviations, "tech-speak" and jargon when explaining -changes that close bugs, especially if the said bugs were filed by users -that did not strike you as particularly techically savvy. Also, be polite, -don't swear. -

-It is customary to prefix changelog entries with the names of the files that -were changed. There's no need to explicitely list each and every last one of -the changed files, especially if the change was small or repetitive -- use -wildcard characters wisely. -

-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 bugs unrelated bugs in -the changelog is considered very 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.") 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 will on the other hand -annoy people who wish to read information about actual changes in the -package. Please 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 real maintainer. You don't have to -follow it, though: if you are certain that you will include the changes from -the NMU in your next release, you can simply close the bugs the normal way. -It's usually polite to note that the bugs were fixed by another developer. -

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

- - * Fixed all outstanding bugs. - -

-This doesn't tell readers anything too useful, obviously. Don't do that(TM). - - - * Applied patch from Jane Random. - -

-What was the patch about? - - - * Late night install target overhaul. - -

-Overhaul which accomplished...? 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 fuckup (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. 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. - + @@ -3600,7 +3726,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. @@ -3928,7 +4054,7 @@ written in Python rather than Perl.

debdiff

-debdiff (from the devscripts package) +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 @@ -4203,7 +4329,8 @@ finalizing a version and listing the package's current bugs.

dpkg-depcheck

-dpkg-depcheck (from the devscripts package) +dpkg-depcheck (from the devscripts +package, ) runs a command under strace to determine all the packages that were used by the said command.

@@ -4288,6 +4415,8 @@ it.