From 5cdb875aaf1789f3fa86c5e7a6f24ffffb33272a Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:08:31 +0000 Subject: [PATCH] Added must/should/may stuff, typo fixes in the policy and rules files, as well as updating the symlink before lib handling in dpkg language Author: srivasta Date: 2000/08/21 01:16:27 Added must/should/may stuff, typo fixes in the policy and rules files, as well as updating the symlink before lib handling in dpkg language git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-62 --- debian/rules | 2 +- packaging.sgml | 5 +- policy.sgml | 590 ++++++++++++++++++++++++++----------------------- 3 files changed, 319 insertions(+), 278 deletions(-) diff --git a/debian/rules b/debian/rules index 59c351f..39b4a0e 100755 --- a/debian/rules +++ b/debian/rules @@ -229,7 +229,7 @@ stamp-packaging: build $(install_file) $$i .. ; \ dpkg-distaddfile -fdebian/files $$i byhand - ; \ done - touch stamp- + touch stamp-packaging define checkdir diff --git a/packaging.sgml b/packaging.sgml index f5fd280..736636a 100644 --- a/packaging.sgml +++ b/packaging.sgml @@ -4528,8 +4528,9 @@ Unfortunately, this was not not always possible, since it highly depends on the behaviour of the filesystem. Some filesystems (such as reisefs) will reorder the files so it - doesn't matter in what order you create them. In newer - versions of dpkg, this is handled automatically. + doesn't matter in what order you create them. Starting with + release 1.7.0 dpkg will reorder the + files itself when building a package.

@@ -116,15 +116,40 @@ each package must satisfy to be included in the distribution.

+

+ In this manual, the words must, should and + may, and the adjectives required>, + recommended and optional, are used to + distinguish the significance of the various guidelines in + this policy document. Packages that do not conform the the + guidelines denoted by must (or required) + will generally not be considered acceptable for the Debian + distribution. Non-conformance with guidelines denoted by + should (or recommended) will generally be + considered a bug, but will not necessarily render a package + unsuitable for distribution. Guidelines denoted by + may (or optional) are truly optional and + adherence is left to the maintainer's discretion. +

+

+ These classifications are roughly equivalent to the bug + severities important (for must or + required directive violations), normal + (for should or recommended directive + violations) and wishlist (for optional + items). +

Also see RFC 2119.

+ +

This manual does not describe the technical mechanisms involved in package creation, installation, and removal. This information can be found in the Debian Packaging Manual and the Debian System Administrators' Manual. Please note that the - footnotes present in this manual are merely informative, - and are not part of Debian policy itself. -

+ footnotes present in this manual are merely informative, + and are not part of Debian policy itself. +

This document assumes familiarity with these other two manuals. Unfortunately, the System Administrators' @@ -344,19 +369,19 @@

must not require a package outside of "main" for - compilation or execution (thus, the package may not + compilation or execution (thus, the package must not declare a "Depends" or "Recommends" relationship on a non-main package),

- must not be so buggy that we refuse to support them, + should not be so buggy that we refuse to support them,

- must meet all policy requirements presented in this + should meet all policy requirements presented in this manual.

@@ -402,16 +427,16 @@ The non-us server

- Some programs with cryptographic program code must be stored + Some programs with cryptographic program code need to be stored on the "non-us" server because of export restrictions of the U.S.

This applies only to packages which contain cryptographic code. A package containing a program with an interface to a cryptographic program or a program that's dynamically linked - against a cryptographic library can be distributed if it is - capable of running without the cryptography library or - program. + against a cryptographic library should not be distributed + via the non-us server if it is capable of running without the + cryptography library or program.

@@ -455,13 +480,12 @@ are fine for the main distribution, provided that the authors do not claim that not donating is immoral, unethical, illegal or something similar; otherwise they must - go in contrib (or non-free, if even distribution is - restricted by such statements).

+ go in non-free.

Packages whose copyright permission notices (or patent problems) do not allow redistribution even of only binaries, - and where no special permission has been obtained, cannot be + and where no special permission has been obtained, must not be placed on the Debian FTP site and its mirrors at all.

@@ -502,9 +526,9 @@ handling.

- The section for each package is specified in the package's - control record. However, the maintainer of the - Debian archive may override this selection to assure the + The section for each package should be specified in the + package's control record. However, the maintainer of + the Debian archive may override this selection to assure the consistency of the Debian distribution.

@@ -515,7 +539,7 @@ Priorities

- Each package is given a certain priority value, + Each package should have a priority value, which is included in the package's control record. This information is used in the Debian package management tool to separate high-priority packages from @@ -575,8 +599,10 @@ all the software that you might reasonably want to install if you didn't know what it was or don't have specialized requirements. This is a much larger system - and includes the X Window System, a full TeX - distribution, and many applications.

+ and includes the X Window System, a full TeX distribution, + and many applications. Note that optional packages should + not conflict with each other. +

extra @@ -591,10 +617,10 @@

- Packages may not depend on packages with lower priority + Packages must not depend on packages with lower priority values (excluding build-time dependencies). In order to - ensure this, the priorities of one or more packages may have - to be adjusted. + ensure this, the priorities of one or more packages must + be adjusted.

@@ -604,7 +630,7 @@

The Debian GNU/Linux distribution is based on the Debian package management system, called dpkg. Thus, - all packages in the Debian distribution have to be provided + all packages in the Debian distribution must be provided in the .deb file format.

@@ -616,7 +642,7 @@ archive.

- Package names may only consist of lower case letters, digits (0-9), + Package names must only consist of lower case letters, digits (0-9), plus (+) or minus (-) signs, and periods (.).

@@ -630,7 +656,7 @@ The maintainer of a package

- Every package must have exactly one maintainer at a + Every package should have exactly one maintainer at a time. This person is responsible that the license of the package's software complies with the policy of the distribution this package is included in.

@@ -663,13 +689,13 @@ stored in the appropriate field of the control record.

- The description must be written so that it tells the user + The description should be written so that it tells the user what they need to know to decide whether to install the package. This description should not just be copied from the blurb for the program. Instructions for configuring - or using the package must not be included -- that is what + or using the package should not be included -- that is what installation scripts, manual pages, Info files, etc. are - for. Copyright statements and other administrivia must + for. Copyright statements and other administrivia should not be included -- that is what the copyright file is for.

 @@ -679,28 +705,29 @@ Dependencies

- Every package has to specify the dependency information - about other packages, that are required for the first to + Every package must specify the dependency information + about other packages that are required for the first to work correctly.

- For example, for any shared libraries required by - dynamically-linked executable binary in a package a - dependency entry has to be provided.

+ For example, a dependency entry must be provided for any + shared libraries required by a dynamically-linked executable + binary in a package.

- It is not necessary for other packages to declare any - dependencies they have on other packages which are marked - Essential (see below).

+ Packages are not required to declare any dependencies they + have on other packages which are marked Essential + (see below), and should not do so unless they depend on a + particular version of that package.

- Sometimes, a package requires another package to be - installed and configured before it can be - installed. In this case, you'll have to specify a - Pre-Depends entry for the package.

+ Sometimes, a package requires another package to be installed + and configured before it can be installed. In this + case, you must specify a Pre-Depends entry for + the package.

- You must not specify a Pre-Depends entry for a + You should not specify a Pre-Depends entry for a package before this has been discussed on the debian-devel mailing list and a consensus about doing that has been reached.

@@ -722,9 +749,9 @@ specify all possible packages individually.

- All packages must use virtual package names where + All packages should use virtual package names where appropriate, and arrange to create new ones if necessary. - They must not use virtual package names (except privately, + They should not use virtual package names (except privately, amongst a cooperating group of packages) unless they have been agreed upon and appear in the list of virtual package names.

@@ -751,7 +778,7 @@ disk usage very small.

- Most of these packages should have the priority value + Most of these packages will have the priority value required or at least important, and many of them will be tagged essential (see below).

@@ -774,7 +801,7 @@

Since these packages can not easily be removed (you'll have to specify an extra force option to - dpkg) this flag must only be used where + dpkg) this flag must not be used unless absolutely necessary. A shared library package must not be tagged @@ -793,7 +820,7 @@ Maintainer scripts

- The package installation scripts must avoid producing + The package installation scripts should avoid producing output which it is unnecessary for the user to see and should rely on dpkg to stave off boredom on the part of a user installing many packages. This means, @@ -843,28 +870,30 @@

Errors which occur during the execution of an installation - script must be checked and the installation - must not continue after an error.

+ script should be checked and the installation should not + continue after an error.

Note, that , in general applies to package maintainer scripts, too.

- Do not use dpkg-divert on a file belonging to - another package without consulting the maintainer of that - package first.

+ You should not use dpkg-divert on a file + belonging to another package without consulting the maintainer + of that package first.

- In order for update-alternatives to work - correctly all the packages which supply an instance of the - `shared' command name (or, in general, filename) must use - it. You can use Conflicts to force the - De-installation of other packages supplying it which do not - (yet) use update-alternatives. It may in - this case be appropriate to specify a conflict on earlier - versions of something--this is an exception to the usual - rule that this is not allowed.

+ All packages which supply an instance of a common command + name (or, in general, filename) should generally use + update-alternatives, so that they may be + installed together. If update-alternatives + is not used, then each package must use Conflicts + to ensure that other packages are de-installed. (In this + case, it may be appropriate to specify a conflict against + earlier versions of something that previously did not use + update-alternatives -- this is an exception to + the usual rule that this not allowed). +

@@ -904,8 +933,7 @@ For package maintainers, only the first 3 digits of the manual version are significant in representing the Standards-Version, and either these 3 digits or - the complete 4 digits can be specified--that's up to the - maintainer. + the complete 4 digits may be specified.

In the past, people specified 4 digits in the @@ -913,7 +941,7 @@ `patch-level changes' don't introduce new policy, it was thought it would be better to relax policy and only require that the first 3 digits are specified. (4 - digits can still be used if someone wants to do so.) + digits may still be used if someone wants to do so.)

@@ -922,7 +950,7 @@ You should regularly, and especially if your package has become out of date, check for the newest Policy Manual available and update your package, if necessary. When your - package complies with the new standards you may update the + package complies with the new standards you should update the Standards-Version source package field and release it.

@@ -931,15 +959,15 @@ Package relationships

- Source packages must specify which binary packages they + Source packages should specify which binary packages they require to be installed or not to be installed in order to build correctly. For example, if building a package - requires a certain compiler, then the compiler must be + requires a certain compiler, then the compiler should be specified as a build-time dependency.

- It will not be necessary to explicitly specify build-time + It is not be necessary to explicitly specify build-time relationships on a minimal set of packages that are always needed to compile, link and put in a Debian package a standard "Hello World!" program written in C or C++. The @@ -947,7 +975,6 @@ an informational list can be found in /usr/share/doc/build-essential/list (which is contained in the build-essential package). -

@@ -961,13 +988,11 @@

- It is a bug if, after unpacking a source package on a - system with the build-essential packages installed and - satisfying the build-time relationships (including the - implied relationships), one cannot build the package and - produce a working binary package suitable for installation - into the binary distribution corresponding to the source - distribution which contained the source package. This + If build-time dependencies are specified, it must be + possible to build the package and produce working binaries + on a system with the build-essential packages installed + and satisfying the build-time relationships (including any + implied relationships). This means in particular that version clauses should be used rigorously in build-time relationships so that one cannot produce bad or inconsistently configured packages when the @@ -979,15 +1004,15 @@

If changes to the source code are made that are generally - applicable please try to get them included in the upstream - version of the package by supplying the upstream authors - with the changes in whatever form they prefer.

+ applicable, they should be sent to the upstream authors + in whatever form they prefer so as to be included in the + upstream version of the package.

If you need to configure the package differently for Debian or for Linux, and the upstream source doesn't - provide a way to configure it the way you need to, please - add such configuration facilities (for example, a new + provide a way to configure it the way you need to, you + should add such configuration facilities (for example, a new autoconf test or #define) and send the patch to the upstream authors, with the default set to the way they originally had it. You can then easily @@ -995,7 +1020,7 @@ wherever is appropriate.

- Please make sure that the configure utility + You should make sure that the configure utility detects the correct architecture specification string (refer to for details).

@@ -1014,8 +1039,11 @@ Documenting your changes

- Document your changes and updates to the source package - properly in the debian/changelog file.

+ You should document your changes and updates to the source + package properly in the debian/changelog file. (Note + that mistakes in changelogs are usually best rectified by + making a new changelog entry rather than "rewriting history" + by editing old changelog entries)

A copy of the file which will be installed in @@ -1023,7 +1051,7 @@ in debian/copyright.

- In non-experimental packages you may only use a format for + In non-experimental packages you must only use a format for debian/changelog which is supported by the most recent released version of dpkg. If your format is not supported and there is general support for @@ -1052,12 +1080,12 @@

Every time you put more than one shell command (this includes using a loop) in a makefile command you - must make sure that errors are trapped. For + must make sure that errors are trapped. For simple compound commands, such as changing directory and then running a program, using && rather than semicolon as a command separator is sufficient. For more complex commands including most loops and - conditionals you must include a separate set -e + conditionals you should include a separate set -e command at the start of every makefile command that's actually one of these miniature shell scripts.

@@ -1111,13 +1139,13 @@ Site-specific programs

- As mandated by the FHS no package should place any + As mandated by the FHS, packages must not place any files in /usr/local, either by putting them in the file system archive to be unpacked by dpkg or by manipulating them in their maintainer scripts.

- However, the package should create empty directories below + However, the package may create empty directories below /usr/local so that the system administrator knows where to place site-specific files. These directories should be removed on package removal if they are @@ -1126,15 +1154,15 @@

Note, that this applies only to directories below /usr/local, not in - /usr/local. The directory /usr/local - itself may only contain the sub-directories listed in + /usr/local. Packages must not create sub-directories + in the directory /usr/local itself, except those listed in FHS, section 4.6. However, you may create directories - below them as you wish. You may not remove any of the + below them as you wish. You must not remove any of the directories listed in 4.6, even if you created them.

- Since /usr/local may be mounted read-only from a - remote server, these directories have to be created and + Since /usr/local can be mounted read-only from a + remote server, these directories must be created and removed by the postinst and prerm maintainer scripts. These scripts must not fail if either of these operations fail. (In the future, it will be @@ -1159,7 +1187,7 @@

If you do create a directory in /usr/local for - local additions to a package, you must ensure that + local additions to a package, you should ensure that settings in /usr/local take precedence over the equivalents in /usr.

@@ -1171,7 +1199,7 @@

The /usr/local directory itself and all the - subdirectories created by the package should have + subdirectories created by the package should (by default) have permissions 2775 (group-writable and set-group-id) and be owned by root.staff.

@@ -1201,9 +1229,9 @@ order--but the behavior should be configurable.

- No package except base-passwd may modify - /etc/passwd, /etc/shadow, or - /etc/group.

+ Packages other than base-passwd must not modify + /etc/passwd, /etc/shadow, + /etc/group or /etc/gshadow.

The UID and GID ranges are as follows: @@ -1211,7 +1239,7 @@ 0-99:

- Globally allocated by the Debian project, must be the + Globally allocated by the Debian project, the same on every Debian system. These ids will appear in the passwd and group files of all Debian systems, new ids in this range being added @@ -1309,7 +1337,7 @@ There are at least two different, yet functionally equivalent, ways of handling these scripts. For the sake of simplicity, this document describes only the symbolic - link method. However, it may not be assumed that this + link method. However, it must not be assumed that this method is being used, and any manipulation of the various runlevel behaviours must be performed using update-rc.d as described below and not by @@ -1363,7 +1391,7 @@ might need to be started before the news server inn so that inn can set up its access lists. In this case, the script that starts - bind should have a lower number than the + bind would have a lower number than the script that starts inn so that it runs first: /etc/rc2.d/S17bind @@ -1376,11 +1404,12 @@ Writing the scripts

- Packages can and should place scripts in - /etc/init.d to start or stop services at boot - time or during a change of runlevel. These scripts should - be named /etc/init.d/package, and they - should accept one argument, saying what to do: + Packages that include daemons for system services should + place scripts in /etc/init.d to start or stop + services at boot time or during a change of runlevel. + These scripts should be named + /etc/init.d/package, and they should + accept one argument, saying what to do: start @@ -1403,7 +1432,7 @@ The start, stop, restart, and - force-reload options must be supported by all + force-reload options should be supported by all scripts in /etc/init.d, the reload option is optional.

@@ -1443,8 +1472,8 @@ Managing the links

- A program is provided, update-rc.d, to handle - the it easier for package maintainers to arrange for the + The program update-rc.d is provided to make + it easier for package maintainers to arrange for the proper creation and removal of /etc/rcn.d symbolic links, or their functional equivalent if another method is being used. @@ -1452,7 +1481,7 @@ postinst and postrm scripts.

- You should use this script to make changes to + You must use this script to make changes to /etc/rcn.d and never either include any /etc/rcn.d symbolic links in the actual archive or manually create or remove the @@ -1507,7 +1536,7 @@ which contained scripts which were run once per machine boot. This has been deprecated in favour of links from /etc/rcS.d to files in /etc/init.d as - described in . No packages may + described in . Packages must not place files in /etc/rc.boot.

@@ -1517,14 +1546,14 @@ Do not include the /etc/rcn.d/* symbolic links in the .deb file system archive! This will cause - problems! You should create them with + problems! You must create them with update-rc.d, as above.

Do not include the /etc/rcn.d/* symbolic links in dpkg's conffiles list! This will cause - problems! Do, however, treat the + problems! You should, however, treat the /etc/init.d scripts as configuration files, either by marking them as conffiles or managing them correctly in the maintainer scripts (see @@ -1611,7 +1640,7 @@ package is purged: if [ purge = "$1" ]; then - update-rc.d acct remove >/dev/null + update-rc.d bind remove >/dev/null fi

@@ -1620,8 +1649,8 @@ Cron jobs

- Packages may not modify the configuration file - /etc/crontab, nor may they modify the files in + Packages must not modify the configuration file + /etc/crontab, and they must not modify the files in /var/spool/cron/crontabs.

@@ -1639,10 +1668,10 @@ /etc/crontab.

- All files installed in any of these directories have to be + All files installed in any of these directories must be scripts (shell scripts, Perl scripts, etc.) so that they can easily be modified by the local system administrator. In - addition, they must be treated as configuration files.

+ addition, they should be treated as configuration files.

If a certain job has to be executed more frequently than @@ -1718,7 +1747,7 @@

- The following formats must be used

+ The following formats should be used

@@ -1762,7 +1791,7 @@ This makes it possible for the user to see what takes so long and when the final daemon has been - started. Please be careful where to put spaces: In the + started. You should be careful where to put spaces: In the example above the system administrator can easily comment out a line if he don't wants to start a specific daemon, while the displayed message still @@ -1774,7 +1803,7 @@

If you have to set up different parameters of the - system upon boot up, you can use this format: + system upon boot up, you should use this format: Setting <parameter> to `<value>'.

@@ -1807,7 +1836,7 @@

when something is executed.

- There a several examples where you have to run a + There are several examples where you have to run a program at system startup or shutdown to perform a specific task. For example, setting the system's clock via `netdate' or killing all processes when the system @@ -1914,7 +1943,7 @@

To achieve a consistent keyboard configuration (i.e., all applications interpret a keyboard event the same way) all - programs in the Debian distribution have to be configured to + programs in the Debian distribution must be configured to comply with the following guidelines.

@@ -2037,35 +2066,35 @@ Environment variables

- No program may depend on environment variables to get + A program must not depend on environment variables to get reasonable defaults. (That's because these environment variables would have to be set in a system-wide configuration file like /etc/profile, which is not supported by all shells.)

- If a program should depend on environment variables for its - configuration, the program has to be changed to fall back to + If a program usually depends on environment variables for its + configuration, the program should be changed to fall back to a reasonable default configuration if these environment variables are not present. If this cannot be done easily (e.g., if the source code of a non-free program is not - available), the program should be replaced by a small + available), the program must be replaced by a small `wrapper' shell script which sets the environment variables - and calls the original program.

+ if they are not already defined, and calls the original program.

Here is an example of a wrapper script for this purpose: #!/bin/sh - BAR=/var/lib/fubar + BAR=${BAR:-/var/lib/fubar} export BAR exec /usr/lib/foo/foo "$@"

Furthermore, as /etc/profile is a configuration - file of the bash package, no other package may + file of the bash package, other packages must not put any environment variables or other commands into that file.

@@ -2078,11 +2107,11 @@ Binaries

- It is not allowed that two packages install programs with + Two different packages must not install programs with different functionality but with the same filenames. (The case of two programs having the same functionality but different implementations is handled via `alternatives.') - If this case happens, one of the programs has to be + If this case happens, one of the programs must be renamed. The maintainers should report this to the developers' mailing and try to find a consensus about which package will have to be renamed. If a consensus can @@ -2112,22 +2141,22 @@ for ELF it has no good effect.

- Debugging symbols are useful for error diagnosis, investigation - of core dumps (which may be submitted by users in bug reports), - or testing and developing the software. Therefore it is - recommended to support building the package with - debugging information through the following interface: - If the environment variable DEB_BUILD_OPTIONS - contains the string debug, compile the software with - debugging information (usually this involves adding the - -g flag to CFLAGS). This allows to generate - a build tree with debugging information. If the environment - variable DEB_BUILD_OPTIONS contains the - string nostrip, do not strip the files at installation + Debugging symbols are useful for error diagnosis, + investigation of core dumps (which may be submitted by users + in bug reports), or testing and developing the + software. Therefore it is recommended to support building + the package with debugging information through the following + interface: If the environment variable + DEB_BUILD_OPTIONS contains the string + debug, compile the software with debugging + information (usually this involves adding the -g + flag to CFLAGS). This allows the generation of a + build tree with debugging information. If the environment + variable DEB_BUILD_OPTIONS contains the string + nostrip, do not strip the files at installation time. This allows to generate a package with debugging - information included. The following makefile snippet - is only an example how to test for either - condition: + information included. The following makefile snippet is only + an example how to test for either condition:

Rationale: Building by default with -g causes more @@ -2176,7 +2205,7 @@

It is up to the package maintainer to decide what compilation options are best for the package. Certain - binaries (such as computationally-intensive programs) may + binaries (such as computationally-intensive programs) will function better with certain flags (-O3, for example); feel free to use them. Please use good judgment here. Don't use flags for the sake of it; only use them @@ -2194,10 +2223,10 @@ package and a static version in the lib-dev package. The shared version must be compiled with -fPIC, and the static version must not be. In other words, each - *.c file is compiled twice.

+ *.c file will need to be compiled twice.

- You have to specify the gcc option -D_REENTRANT + You must specify the gcc option -D_REENTRANT when building a library (either static or shared) to make the library compatible with LinuxThreads.

@@ -2245,7 +2274,7 @@

- Packages that use libtool to create shared libraries must + Packages that use libtool to create shared libraries should include the .la files in the -dev packages, with the exception that if the package relies on libtool's libltdl library, in which case the .la @@ -2255,7 +2284,7 @@

- Please make sure that you use only released versions of + You must make sure that you use only released versions of shared libraries to build your packages; otherwise other users will not be able to run your binaries properly. Producing source packages that depend on @@ -2293,7 +2322,7 @@ at a time (after all, different development versions are likely to have the same header files in them, causing a filename clash if both are installed). Typically the - development version will also need an exact version + development version should also have an exact version dependency on the runtime library, to make sure that compilation and linking happens correctly.

@@ -2307,7 +2336,7 @@

If your package has some run-time support programs which - use the shared library you must not put them in + use the shared library you must not put them in the shared library package. If you do that then you won't be able to install several versions of the shared library without getting filename clashes. Instead, either create @@ -2319,21 +2348,21 @@

If you have several shared libraries built from the same - source tree you can lump them all together into a single + source tree you may lump them all together into a single shared library package, provided that you change all their sonames at once (so that you don't get filename clashes if you try to install different versions of the combined shared libraries package).

- Follow the directions in the Debian Packaging + You should follow the directions in the Debian Packaging Manual for putting the shared library in its package, - and make sure you include a shlibs control area + and you must include a shlibs control area file with details of the dependencies for packages which use the library.

- Shared libraries should not be installed + Shared libraries should not be installed executable, since ld.so does not require this and trying to execute a shared library results in a core dump.

@@ -2355,24 +2384,24 @@

Shell scripts (sh and bash) should almost certainly start with set -e so that - errors are detected. Every script must use + errors are detected. Every script should use set -e or check the exit status of every command.

- The standard shell interpreter `/bin/sh' may be a + The standard shell interpreter `/bin/sh' can be a symbolic link to any POSIX compatible shell. Thus, shell - scripts specifying `/bin/sh' as interpreter may + scripts specifying `/bin/sh' as interpreter should only use POSIX features. If a script requires non-POSIX features from the shell interpreter, the appropriate shell - has to be specified in the first line of the script (e.g., - `#!/bin/bash') and the package has to depend on + must be specified in the first line of the script (e.g., + `#!/bin/bash') and the package must depend on the package providing the shell (unless the shell package is marked `Essential', e.g., in the case of bash).

- Restrict your script to POSIX features when possible so + You may wish to restrict your script to POSIX features when possible so that it may use /bin/sh as its interpreter. If your script works with ash, it's probably POSIX compliant, but if you are in doubt, use @@ -2398,8 +2427,8 @@ c-shell virtual package.

- Any scripts which create files in world-writable - directories (e.g., in /tmp) have to use a + Any scripts which create files in world-writeable + directories (e.g., in /tmp) must use a mechanism which will fail if a file with the same name already exists.

@@ -2458,17 +2487,17 @@ Device files

- No package may include device files in the package file + Packages must not include device files in the package file tree.

If a package needs any special device files that are not - included in the base system, it has to call + included in the base system, it must call makedev in the postinst script, after asking the user for permission to do so.

- No package should remove any device files in the + Packages must not remove any device files in the postrm or any other script. This is left to the system administrator.

@@ -2522,12 +2551,12 @@ Location

Any configuration files created or used by your package - should reside in /etc. If there are several you + must reside in /etc. If there are several you should consider creating a subdirectory of /etc named after your package.

- If your packages creates or uses configuration files + If your package creates or uses configuration files outside of /etc, and it is not feasible to modify the package to use the /etc, you should still put the files in /etc and create symbolic links to @@ -2546,7 +2575,7 @@ upgrade

-

configuration files should be preserved when the +

configuration files must be preserved when the package is removed, and only deleted when the package is purged.

 @@ -2596,7 +2625,7 @@ upgrades), and otherwise be good citizens.

- The scripts need not configure every possible option for + The scripts are not required to configure every possible option for the package, but only those necessary to get the package running on a given system. Ideally the sysadmin should not have to do any configuration other than that done @@ -2615,8 +2644,8 @@ (not conffiles).

- These two styles of configuration file handling must - not be mixed, for that way lies madness: + These two styles of configuration file handling must + not be mixed, for that way lies madness: dpkg will ask about overwriting the file every time the package is upgraded.

@@ -2625,12 +2654,12 @@ Sharing configuration files

- Only packages that are tagged conflicting with - each other may specify the same file as + Packages that are not tagged as conflicting with + each other must not specify the same file as conffile.

- The maintainer scripts should not alter the conffile of + The maintainer scripts must not alter the conffile of any package, including the one the scripts belong to.

@@ -2641,7 +2670,7 @@ owner of the configuration file, i.e. it will be the package to list that distributes the file and lists it as a conffile. Other packages that use the - configuration file should depend on the owning package if + configuration file must depend on the owning package if they require the configuration file to operate. If the other package will use the configuration file if present, but is capable of operating without it, no dependency need @@ -2651,7 +2680,7 @@ If it is desirable for two or more related packages to share a configuration file and for all of the related packages to be able to modify that configuration - file, then the following should done: + file, then the following should be done:

@@ -2712,7 +2741,7 @@ configuration file elsewhere in /etc. Only if the program doesn't support a site-wide default configuration and the package maintainer doesn't have time to add it - should a default per-user file be placed in + may a default per-user file be placed in /etc/skel.

@@ -2753,7 +2782,7 @@ /var/log/package.

- Make sure that any log files are rotated occasionally so + Log files must be rotated occasionally so that they don't grow indefinitely; the best way to do this is to drop a script into the directory /etc/logrotate.d and use the facilities provided by @@ -2777,7 +2806,7 @@

- Make sure that any log files are removed when the package is + Log files should be removed when the package is purged (but not when it is only removed), by checking the argument to the postrm script (see the Debian Packaging Manual for details).

@@ -2791,7 +2820,7 @@ The rules in this section are guidelines for general use. If necessary you may deviate from the details below. However, if you do so you must make sure that what is done - is secure and you must try to be as consistent as possible + is secure and you should try to be as consistent as possible with the rest of the system. You should probably also discuss it on debian-devel first.

@@ -2827,7 +2856,7 @@ execute them.

- Do not arrange that the system administrator can only + You must not arrange that the system administrator can only reconfigure the package to correspond to their local security policy by changing the permissions on a binary. Ordinary files installed by dpkg (as opposed @@ -2844,11 +2873,12 @@ make some files in the binary package be owned by this user or group, or you may need to compile the user or group id (rather than just the name) into the binary - (though this latter should be avoided if possible). In - this case you need a statically allocated id.

+ (though this latter should be avoided if possible, as in + this case you need a statically allocated id).

- You must ask for a user or group id from the base system + If you need a statically allocated id, you must ask for a + user or group id from the base system maintainer, and must not release the package until you have been allocated one. Once you have been allocated one you must make the package depend on a version of the base @@ -2860,9 +2890,9 @@ it is possible).

- On the other hand, the program may able to determine the + On the other hand, the program might be able to determine the uid or gid from the group name at runtime, so that a - dynamic id can be used. In this case you must choose an + dynamic id can be used. In this case you should choose an appropriate user or group name, discussing this on debian-devel and checking with the base system maintainer that it is unique and that they do not @@ -2890,14 +2920,14 @@

If a program needs to specify an architecture specification - string in some place, the following format has to be used: + string in some place, the following format should be used: <arch>-<os> where `<arch>' is one of the following: i386, alpha, arm, m68k, powerpc, sparc and `<os>' is one of: linux, gnu. Use of gnu in this string is reserved for the GNU/Hurd - operating system. .

+ operating system.

Note, that we don't want to use `<arch>-debian-linux' to apply to the rule `architecture-vendor-os' since this @@ -2918,20 +2948,20 @@

If a package requires a new entry in one of these files, the - maintainer has to get in contact with the + maintainer should get in contact with the netbase maintainer, who will add the entries and release a new version of the netbase package.

- The configuration file /etc/inetd.conf may be - modified by the package's scripts only via the + The configuration file /etc/inetd.conf must not be + modified by the package's scripts except via the update-inetd script or the DebianNet.pm Perl module.

If a package wants to install an example entry into - /etc/inetd.conf, the entry has to be preceded with + /etc/inetd.conf, the entry must be preceded with exactly one hash character (#). Such lines are treated as `commented out by user' by the update-inetd script and are not changed or @@ -2952,7 +2982,7 @@ The files /var/run/utmp, /var/log/wtmp and /var/log/lastlog must be installed writeable by group utmp. Programs who need to modify those files must - be installed install setgid utmp. + be installed setgid utmp.

@@ -2973,26 +3003,26 @@ administrator.

- Thus, every program that launches an editor or pager has to + Thus, every program that launches an editor or pager must use the EDITOR or PAGER environment variables to determine the editor/pager the user wants to get started. If these variables are not set, the programs /usr/bin/editor - and /usr/bin/pager have to be used, respectively.

+ and /usr/bin/pager should be used, respectively.

These two files are managed through `alternatives.' That is, - every package providing an editor or pager has to call the + every package providing an editor or pager must call the update-alternatives script to register these programs.

If it is very hard to adapt a program to make us of the - EDITOR and PAGER variable, that program should be configured + EDITOR and PAGER variable, that program may be configured to use /usr/bin/sensible-editor and /usr/bin/sensible-pager as editor or pager program, respectively. These are two scripts provided in the Debian base system that check the EDITOR and PAGER variables and - launches the appropriate program or falls back to + launch the appropriate program or fall back to /usr/bin/editor and /usr/bin/pager, automatically.

@@ -3004,8 +3034,8 @@

Since the Debian base system already provides an editor and - a pager program, there is no need for a package to depend on - `editor' and `pager', nor is it necessary for a package to + a pager program, it is not required for a package to depend on + `editor' and `pager', nor is it required for a package to provide such virtual packages.

@@ -3013,7 +3043,7 @@ Web servers and applications

- This section describes the locations and URLs that have to + This section describes the locations and URLs that should be used by all web servers and web application in the Debian system.

@@ -3025,7 +3055,7 @@ /usr/lib/cgi-bin/<cgi-bin-name> - and can be referred to as + and should be referred to as http://localhost/cgi-bin/<cgi-bin-name>

@@ -3049,7 +3079,7 @@

Web Applications should try to avoid storing files in - the Web Document Root. Instead use the + the Web Document Root. Instead they should use the /usr/share/doc/<package> directory for documents and register the Web Application via the menu package. If access to the web-root is unavoidable then use @@ -3070,7 +3100,7 @@

Debian packages which process electronic mail, whether mail-user-agents (MUAs) or mail-transport-agents (MTAs), - must make sure that they are compatible with the + must make sure that they are compatible with the configuration decisions below. Failure to do this may result in lost mail, broken From: lines, and other serious brain damage!

@@ -3083,10 +3113,10 @@

All Debian MUAs, MTAs, MDAs and other mailbox accessing - programs (like IMAP daemons) have to lock the mailbox in a - NFS-safe way. This means that fcntl() locking has + programs (like IMAP daemons) must lock the mailbox in an + NFS-safe way. This means that fcntl() locking must to be combined with dot locking. To avoid dead locks, a - program has to use fcntl() first and dot locking + program should use fcntl() first and dot locking after this or alternatively implement the two locking methods in a non blocking way

@@ -3110,9 +3140,9 @@ Mailboxes must be writable by group mail.

- The mail spool is 2775 mail.mail, and MUAs need to + The mail spool is 2775 mail.mail, and MUAs should be setgid mail to do the locking mentioned above (and - obviously need to avoid accessing other users' mailboxes + must obviously avoid accessing other users' mailboxes using this privilege).

@@ -3121,7 +3151,7 @@ which the sysadmin and postinst scripts may edit. After /etc/aliases is edited the program or human editing it must call newaliases. All MTA - packages should come with a newaliases program, + packages must come with a newaliases program, even if it does nothing, but older MTA packages do not do this so programs should not fail if newaliases cannot be found.

@@ -3132,10 +3162,10 @@ supported. Use a .forward file instead.

- The location for the rmail program used by UUCP - for incoming mail is /usr/sbin/rmail, as per the + The rmail program used by UUCP + for incoming mail should be /usr/sbin/rmail, as per the FHS. Likewise, rsmtp, for receiving - batch-SMTP-over-UUCP, is in /usr/sbin/rsmtp if it + batch-SMTP-over-UUCP, should be /usr/sbin/rsmtp if it is supported.

@@ -3182,7 +3212,7 @@ /etc/news/organization -

A string which shall appear as the +

A string which should appear as the organization header for all messages posted by NNTP clients on the machine

@@ -3226,7 +3256,7 @@

- Do not create two versions (one with X support and one + You should not create two versions (one with X support and one without) of your package.

@@ -3423,21 +3453,26 @@

- -

- Application defaults files must be installed in the - directory /usr/X11R6/lib/X11/app-defaults/. They should - not be registered as conffiles or otherwise treated as - configuration files. Customization of programs' X resources may - be supported with the provision of a file with the same name as - that of the package placed in the /etc/X11/Xresources/ - directory, which should be registered as a conffile. - Important: packages that install files into the - /etc/X11/Xresources/ directory must declare a - conflict with xbase (<< 3.3.2.3a-2); if this is - not done it is possible for the installing package to destroy a - previously-existing /etc/X11/Xresources file - which had been customized by the system administrator. + +

+ Application defaults files must be installed in the + directory /usr/X11R6/lib/X11/app-defaults/. + +

Note: This shall change very shortly.

+ + They should not be registered as conffiles or + otherwise treated as configuration files. Customization of + programs' X resources may be supported with the provision of + a file with the same name as that of the package placed in + the /etc/X11/Xresources/ directory, which must + registered as a conffile. Important: + packages that install files into the + /etc/X11/Xresources/ directory must + declare a conflict with xbase (<< + 3.3.2.3a-2); if this is not done it is possible for the + installing package to destroy a previously-existing + /etc/X11/Xresources file which had been + customized by the system administrator.

Rationale: clarifies the language to properly address the package maintainer, not the system @@ -3451,7 +3486,7 @@ Packages using the X Window System should abide by the FHS standard whenever possible; they should install binaries, libraries, manual pages, and other files in FHS-mandated - locations wherever possible. This means that files should + locations wherever possible. This means that files must not be installed into /usr/X11R6/bin/, /usr/X11R6/lib/, or /usr/X11R6/man/ unless this is necessary for the package to operate properly. @@ -3527,11 +3562,11 @@

Games which require protected, privileged access to - high-score files, savegames, etc., must be made + high-score files, savegames, etc., may be made set-group-id (mode 2755) and owned by root.games, and use files and directories with appropriate permissions (770 root.games, for - example). They must not be made + example). They must not be made set-user-id, as this causes security problems. (If an attacker can subvert any set-user-id game they can overwrite the executable of any other, causing other players @@ -3546,7 +3581,7 @@ configured by the upstream authors to install with their data files or other static information made unreadable so that they can only be accessed through set-id programs - provided. Do not do this in a Debian package: anyone can + provided. You should not do this in a Debian package: anyone can download the .deb file and read the data from it, so there is no point making the files unreadable. Not making the files unreadable also means that you don't have @@ -3569,18 +3604,25 @@ Manual pages

- You must install manual pages in nroff source + You should install manual pages in nroff source form, in appropriate places under /usr/share/man. You should only use sections 1 to 9 (see the FHS for more - details). You must not install a preformatted `cat + details). You must not install a preformatted `cat page'.

+

+ Each program, utiltiy, and function should have an + associated manpage included in the same package. It is + suggested that all configuration files also have a manual + page included as well. +

+

If no manual page is available for a particular program, - utility or function and this is reported as a bug on + utility, function or configuration file and this is reported as a bug on debian-bugs, a symbolic link from the requested manual page to the manual page - should be provided. This symbolic link can be created from + may be provided. This symbolic link can be created from debian/rules like this: ln -s ../man7/undocumented.7.gz \ @@ -3609,8 +3651,8 @@ is better to use a symbolic link than the .so feature, but there is no need to fiddle with the relevant parts of the upstream source to change from .so to - symlinks--don't do it unless it's easy. Do not create hard - links in the manual page directories, and do not put + symlinks--don't do it unless it's easy. You should not create hard + links in the manual page directories, nor put absolute filenames in .so directives. The filename in a .so in a manpage should be relative to the base of the manpage tree (usually @@ -3625,7 +3667,7 @@ They should be compressed with gzip -9.

- Your package must call install-info to update the Info + Your package should call install-info to update the Info dir file, in its post-installation script: @@ -3645,14 +3687,14 @@ the second is used when creating a new one.

- You must remove the entries in the pre-removal script: + You should remove the entries in the pre-removal script: install-info --quiet --remove /usr/share/info/foobar.info

If install-info cannot find a description entry - in the Info file you will have to supply one. See for details.

@@ -3660,7 +3702,7 @@ Additional documentation

- Any additional documentation that comes with the package can + Any additional documentation that comes with the package may be installed at the discretion of the package maintainer. Text documentation should be installed in a directory /usr/share/doc/package, where @@ -3757,9 +3799,9 @@

In addition, the copyright file must say where the upstream - sources (if any) were obtained, and explain briefly what + sources (if any) were obtained, and should explain briefly what modifications were made in the Debian version of the package - compared to the upstream one. It must name the original + compared to the upstream one. It should name the original authors of the package and the Debian maintainer(s) who were involved with its creation.

@@ -3801,7 +3843,7 @@

- Do not use the copyright file as a general README + You should not use the copyright file as a general README file. If your package has such a file it should be installed in /usr/share/doc/package/README or README.Debian or some other appropriate place.

@@ -3828,37 +3870,35 @@ Changelog files

- This installed file must contain a copy of the - debian/changelog file from your Debian source tree, - and a copy of the upstream changelog file if there is one. - The debian/changelog file should be installed in - /usr/share/doc/package as - changelog.Debian.gz. If the upstream changelog - file is text formatted, it must be accessible as - /usr/share/doc/package/changelog.gz. If - the upstream changelog file is HTML formatted, it must be - accessible as - /usr/share/doc/package/changelog.html.gz. - A plain text version of the changelog must be accessible as - /usr/doc/package/changelog.gz (this can - be created by lynx -dump -nolist). If the upstream - changelog files do not already conform to this naming - convention, then this may be achieved by either renaming the - files or adding a symbolic link at the packaging developer's - discretion. + Packages that are not Debian-native must contain a copy + of debian/changelog file from the Debian source + tree in /usr/share/doc/package + as changelog.Debian.gz. If an upstream + changelog is available, it should be accessible as + /usr/share/doc/package/changelog.gz + in plain text. If the upstream changelog is distributed + in HTML, it should be made available in that form as + /usr/share/doc/package/changelog.html.gz + and the changelog.gz should be generated using, eg, + lynx -dump -nolist. If the upstream changelog files do + not already conform to this naming convention, then this may + be achieved either by renaming the files, or adding a symbolic + link, at the maintainer's discretion.

Rationale: People should not have to look into two - places ofr upstream changelogs merely because they are + places for upstream changelogs merely because they are in HTML format.

-

- Both should be installed compressed using gzip -9, - as they will become large with time even if they start out - small.

+ +

+ All these files should be installed compressed using gzip -9, + as they will become large with time even if they start out + small. +

If the package has only one changelog which is used both as -- 2.39.2