X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=7de382d39ff9ba4dd367575ecbb95db7f64518ad;hb=3c33e7cdf315b5168b19ce2aaed12e991b309b3b;hp=f7b33664a4c9d4d9f5bee85f63d2c66331a54b0b;hpb=da577f74fbf53ebe8b936a6fe0618e96dd35ba55;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index f7b3366..7de382d 100644 --- a/policy.sgml +++ b/policy.sgml @@ -753,7 +753,8 @@ with required, important, standard or optional priorities, or are only likely to be useful if you already know what they are or have specialized - requirements. + requirements (such as packages containing only detached + debugging symbols).

@@ -1011,29 +1012,23 @@ (see below), and should not do so unless they depend on a particular version of that package.

- Essential is defined as the minimal set of functionality - that must be available and usable on the system even - when packages are in an unconfigured (but unpacked) - state. This is needed to avoid unresolvable dependency - loops on upgrade. If packages add unnecessary - dependencies on packages in this set, the chances that - there will be an unresolvable - dependency loop caused by forcing these Essential - packages to be configured first before they need to be - is greatly increased. It also increases the chances - that frontends will be unable to - calculate an upgrade path, even if one - exists. + Essential is needed in part to avoid unresolvable dependency + loops on upgrade. If packages add unnecessary dependencies + on packages in this set, the chances that there + will be an unresolvable dependency loop + caused by forcing these Essential packages to be configured + first before they need to be is greatly increased. It also + increases the chances that frontends will be unable to + calculate an upgrade path, even if one + exists.

- Also, it's pretty unlikely that functionality from - Essential shall ever be removed (which is one reason why - care must be taken before adding to the Essential - packages set), but packages have been removed - from the Essential set when the functionality moved to a - different package. So depending on these packages - just in case they stop being essential does way - more harm than good. + Also, functionality is rarely ever removed from the + Essential set, but packages have been removed from + the Essential set when the functionality moved to a + different package. So depending on these packages just + in case they stop being essential does way more harm + than good.

@@ -1120,10 +1115,13 @@ Essential packages

- Some packages are tagged essential for a system - using the Essential control file field. - The format of the Essential control field is - described in . + Essential is defined as the minimal set of functionality that + must be available and usable on the system at all times, even + when packages are in an unconfigured (but unpacked) state. + Packages are tagged essential for a system using the + Essential control file field. The format of the + Essential control field is described in .

@@ -1147,6 +1145,19 @@ appropriate.

+

+ Maintainers should take great care in adding any programs, + interfaces, or functionality to essential packages. + Packages may assume that functionality provided by + essential packages is always available without + declaring explicit dependencies, which means that removing + functionality from the Essential set is very difficult and is + almost never done. Any capability added to an + essential package therefore creates an obligation to + support that capability as part of the Essential set in + perpetuity. +

+

You must not tag any packages essential before this has been discussed on the debian-devel @@ -1205,8 +1216,8 @@ Package maintainer scripts may prompt the user if necessary. Prompting should be done by communicating through a program, such as debconf, which - conforms to the Debian Configuration management - specification, version 2 or higher. Prompting the user by + conforms to the Debian Configuration Management + Specification, version 2 or higher. Prompting the user by other means, such as by hand From the Jargon file: by hand 2. By extension, writing code which does something in an explicit or @@ -1217,7 +1228,7 @@

- The Debian Configuration management specification is included + The Debian Configuration Management Specification is included in the debconf_specification files in the debian-policy package. It is also available from the Debian web mirrors at @@ -1226,8 +1237,8 @@

- Packages which use the Debian Configuration management - specification may contain an additional + Packages which use the Debian Configuration Management + Specification may contain an additional config script and a templates file in their control archive The control.tar.gz inside the .deb. @@ -1239,18 +1250,18 @@ Therefore it must work using only the tools present in essential packages. Debconf or another tool that - implements the Debian Configuration management - specification will also be installed, and any + implements the Debian Configuration Management + Specification will also be installed, and any versioned dependencies on it will be satisfied before preconfiguration begins.

- Packages which use the Debian Configuration management - specification must allow for translation of their messages - by using a gettext-based system such as the one provided by - the po-debconf package. + Packages which use the Debian Configuration Management + Specification must allow for translation of their user-visible + messages by using a gettext-based system such as the one + provided by the po-debconf package.

@@ -3425,8 +3436,7 @@ Package: libc6 scripts this means that you almost always need to use set -e (this is usually true when writing shell scripts, in fact). It is also important, of course, that - they don't exit with a non-zero status if everything went - well. + they exit with a zero status if everything went well.

@@ -7057,18 +7067,19 @@ strip --strip-unneeded your-lib support -a and -o as binary logical operators. local to create a scoped variable must be - supported; however, local may or may not preserve - the variable value from an outer scope and may or may not - support arguments more complex than simple variables. Only - uses such as: + supported, including listing multiple variables in a single + local command and assigning a value to a variable at the + same time as localizing it. local may or + may not preserve the variable value from an outer scope if + no assignment is present. Uses such as: fname () { - local a - a='' - # ... use a ... + local a b c=delta d + # ... use a, b, c, d ... } - must be supported. + must be supported and must set the value of c to + delta. If a shell script requires non-SUSv3 features from the shell @@ -9285,7 +9296,7 @@ install-info --quiet --remove /usr/share/info/foobar.info To view the copyright file for a package you could use this command: - dpkg --fsys-tarfile filename.deb | tar xOf - \*/copyright | pager + dpkg --fsys-tarfile filename.deb | tar xOf - --wildcards \*/copyright | pager

@@ -10549,26 +10560,48 @@ install-info --quiet --remove /usr/share/info/foobar.info supposing that a smailwrapper package wishes to install a wrapper around /usr/sbin/smail: - if [ install = "$1" ]; then - dpkg-divert --package smailwrapper --add --rename \ - --divert /usr/sbin/smail.real /usr/sbin/smail - fi - Testing $1 is necessary so that the script - doesn't try to add the diversion again when - smailwrapper is upgraded. The --package - smailwrapper ensures that smailwrapper's - copy of /usr/sbin/smail can bypass the diversion and - get installed as the true version. + dpkg-divert --package smailwrapper --add --rename \ + --divert /usr/sbin/smail.real /usr/sbin/smail + The --package smailwrapper ensures that + smailwrapper's copy of /usr/sbin/smail + can bypass the diversion and get installed as the true version. + It's safe to add the diversion unconditionally on upgrades since + it will be left unchanged if it already exists, but + dpkg-divert will display a message. To suppress that + message, make the command conditional on the version from which + the package is being upgraded: + + if [ upgrade != "$1" ] || dpkg --compare-versions "$2" lt 1.0-2; then + dpkg-divert --package smailwrapper --add --rename \ + --divert /usr/sbin/smail.real /usr/sbin/smail + fi + where 1.0-2 is the version at which the + diversion was first added to the package. Running the command + during abort-upgrade is pointless but harmless.

The postrm has to do the reverse: - if [ remove = "$1" ]; then + if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1" ]; then + dpkg-divert --package smailwrapper --remove --rename \ + --divert /usr/sbin/smail.real /usr/sbin/smail + fi + If the diversion was added at a particular version, the + postrm should also handle the failure case of upgrading from an + older version (unless the older version is so old that direct + upgrades are no longer supported): + + if [ abort-upgrade = "$1" ] && dpkg --compare-versions "$2" lt 1.0-2; then dpkg-divert --package smailwrapper --remove --rename \ --divert /usr/sbin/smail.real /usr/sbin/smail fi - + where 1.02-2 is the version at which the + diversion was first added to the package. The postrm should not + remove the diversion on upgrades both because there's no reason to + remove the diversion only to immediately re-add it and since the + postrm of the old package is run after unpacking so the removal of + the diversion will fail.