From 8714ea1b0fedf8009b6d7588988a97407daa48fe Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:09:07 +0000 Subject: [PATCH] * The minimal change in version number is so that people can test and Author: srivasta Date: 2001/01/18 07:44:41 * The minimal change in version number is so that people can test and root out the bugs in this document before we make everyone change to this version. * Document the Enhances relationship * Removed the restriction that one, and exactly one, person must maintain a package. closes: Bug#51879 * Fixed a typo, and added the nogroup name, in uid/gid section of policy. closes: Bug#53496 * Fixed a misstatement in policy about not needing to depend on packages in the base system (not true -- the Essential tag is significant) closes: Bug#53700 * Clarified update-rc.d stuff closes: Bug#55048 * We have already included the material for shlibdep changes, and most of this is not relevant to policy anyway. closes: Bug#55730 * makedev--> MAKEDEV closes: Bug#57154 * Added restrictions on the files in /usr/share/doc/ closes: Bug#59403 * Changed location of a paragraph about copyright files into the section that deals with copyright files. closes: Bug#65765 * init script configuration variables closes: Bug#66912 * Clarifed language about packages sharing a conffile need to be marked as conflicting closes: Bug#76028 git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-69 --- debian/changelog | 28 +++++++ policy.sgml | 167 +++++++++++++++++++++++++++++---------- upgrading-checklist.html | 24 ++++-- 3 files changed, 174 insertions(+), 45 deletions(-) diff --git a/debian/changelog b/debian/changelog index ee56c7e..89bd2d2 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,31 @@ +debian-policy (3.2.1.2) unstable; urgency=low + + * The minimal change in version number is so that people can test and + root out the bugs in this document before we make everyone change to + this version. + * Document the Enhances relationship + * Removed the restriction that one, and exactly one, person must + maintain a package. closes: Bug#51879 + * Fixed a typo, and added the nogroup name, in uid/gid section of + policy. closes: Bug#53496 + * Fixed a misstatement in policy about not needing to depend on packages + in the base system (not true -- the Essential tag is significant) + closes: Bug#53700 + * Clarified update-rc.d stuff closes: Bug#55048 + + * We have already included the material for shlibdep changes, and most + of this is not relevant to policy anyway. closes: Bug#55730 + * makedev--> MAKEDEV closes: Bug#57154 + * Added restrictions on the files in /usr/share/doc/ + closes: Bug#59403 + * Changed location of a paragraph about copyright files into the section + that deals with copyright files. closes: Bug#65765 + * init script configuration variables closes: Bug#66912 + * Clarifed language about packages sharing a conffile need to be marked + as conflicting closes: Bug#76028 + + -- Manoj Srivastava Thu, 18 Jan 2001 01:43:58 -0600 + debian-policy (3.2.1.1) unstable; urgency=low * Don't compress version.ent in the doc directory (it gets bigger!) diff --git a/policy.sgml b/policy.sgml index 8a4dfc5..54a1173 100644 --- a/policy.sgml +++ b/policy.sgml @@ -411,8 +411,8 @@

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

@@ -719,13 +719,14 @@ The maintainer of a package - -

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

- +

+ Every package must have a maintainer (the maintainer may + be one person or a group of people reachable from a common + email address, such as a mailing list). The maintainer is + responsible for ensuring that the package is placed in + the appropriate distribution +

+

The maintainer must be specified in the Maintainer control field with the correct name @@ -1151,11 +1152,6 @@ making a new changelog entry rather than "rewriting history" by editing old changelog entries)

-

- A copy of the file which will be installed in - /usr/share/doc/package/copyright should be - in debian/copyright.

-

In non-experimental packages you must only use a format for debian/changelog which is supported by the most @@ -2801,8 +2797,8 @@

This is done using the Depends, Recommends, - Suggests, Conflicts, Provides and - Replaces control file fields. + Suggests, Enhances, Conflicts, + Provides and Replaces control file fields.

@@ -2905,13 +2901,14 @@ Binary Dependencies - Depends, - Recommends, Suggests, Pre-Depends + Recommends, Suggests, Enhances, + Pre-Depends

- These four fields are used to declare a dependency by one - package on another. They appear in the depending package's - control file. + These five fields are used to declare a dependency + relationship by one package on another. They appear in the + depending package's control file.

@@ -2975,7 +2972,16 @@ perhaps enhance its usefulness, but that installing this one without them is perfectly reasonable.

+ + Enhances + +

+ This field is similar to Suggests but works in the + opposite direction. It is used to declare that a + package can enhance the functionality of another + package. +

Pre-Depends @@ -3818,7 +3824,7 @@ each system, should use `adduser --system' to create the group and/or user. adduser will check for the existence of the user or group, and - if necessary choose an unused id based on the ranged + if necessary choose an unused id based on the ranges specified in adduser.conf.

@@ -3864,7 +3870,8 @@ 65534: -

User `nobody.'

 +

User `nobody.' The corresponding gid refers + to the group `nogroup.'

65535: @@ -3893,11 +3900,12 @@ 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 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 - manually installing symlinks. For information on the + link method. However, it must not be assumed by maintainer + scripts that this method is being used, and any automated + manipulation of the various runlevel behaviours by + maintainer scripts must be performed using `update-rc.d' + as described below and not by manually installing or + removing symlinks. For information on the implementation details of the other method, implemented in the file-rc package, please refer to the documentation of that package.

@@ -4022,6 +4030,33 @@ test -f program-executed-later-in-script || exit 0

+ +

+ Often there are some values in the `init.d' + scripts that a system administrator will frequently want + to change. While the scripts are frequently conffiles, + modifying them requires that the administrator merge in + their changes each time the package is upgraded and the + conffile changes. To ease the burden on the system + administrator, such configurable values should not be + placed directly in the script. Instead, they should be + placed in a file in `/etc/default', which + typically will have the same base name as the + `init.d' script. This extra file can be sourced + by the script when the script runs. It must contain only + variable settings and comments. +

+ +

+ To ensure that vital configurable values are always + available, the `init.d' script should set default + values for each of the shell variables it uses before + sourcing the /etc/default/ file. Also, since the + `/etc/default/' file is often a conffile, the + `init.d' script must behave sensibly without + failing if it is deleted. +

+ @@ -4135,7 +4170,10 @@ nameserver a HUP signal (causing it to reload its configuration); this way the user can say /etc/init.d/bind reload to reload the name - server.

+ server. The script has one configurable value, which can + be used to pass parameters to the named program at + startup. +

@@ -4145,11 +4183,19 @@ # <rob@mars.org>, edited by iwj and cs test -x /usr/sbin/named || exit 0 + + # Source defaults file. + PARAMS='' + if [ -f /etc/default/bind ]; then + . /etc/default/bind + fi + case "$1" in start) echo -n "Starting domain name service: named" - start-stop-daemon --start --quiet --exec /usr/sbin/named + start-stop-daemon --start --quiet --exec /usr/sbin/named \ + -- $PARAMS echo "." ;; stop) @@ -4162,7 +4208,8 @@ echo -n "Restarting domain name service: named" start-stop-daemon --stop --quiet \ --pidfile /var/run/named.pid --exec /usr/sbin/named - start-stop-daemon --start --verbose --exec /usr/sbin/named + start-stop-daemon --start --verbose --exec /usr/sbin/named \ + -- $PARAMS echo "." ;; force-reload|reload) @@ -4178,8 +4225,22 @@ esac exit 0 -

- + +

+ +

+ Complementing the above init script is a file + '/etc/default/bind', which contains configurable + parameters used by the script. +

+

+ + # Specified parameters to pass to named. See named(8). + # You may uncomment the following line, and edit to taste. + #PARAMS="-u nobody" + +

+

Another example on which to base your /etc/init.d scripts is in /etc/init.d/skeleton.

@@ -5063,7 +5124,7 @@

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

@@ -5225,9 +5286,10 @@ Sharing configuration files

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

+ Packages which specify the same file as + `conffile' must be tagged as conflicting + with each other. +

The maintainer scripts must not alter the conffile of @@ -5604,10 +5666,18 @@ /usr/bin/sensible-editor does.

- Since the Debian base system already provides an editor and - a pager program, it is not required for a package to depend on + 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.

+ provide such virtual packages. + +

+ The Debian base system already provides an editor and + a pager program, +

+ +

+ + @@ -6298,6 +6368,17 @@ in the binary package. However, you don't need to install the instructions for building and installing the package, of course!

+ +

+ Files in /usr/share/doc should not be referenced by + any program, and the system administrator should be able to + delete them without causing any programs to break. Any files + that are referenced by programs but are also useful as + standalone documentation should be installed under + /usr/share/<package$gt;/ and symlinked in + /usr/share/doc/<package$gt;/. +

+ @@ -6379,6 +6460,12 @@ 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.

+ +

+ A copy of the file which will be installed in + /usr/share/doc/package/copyright should be + in debian/copyright.

+

/usr/share/doc/<package-name> may be a symbolic link to a @@ -6387,7 +6474,7 @@ relationship on the second. These rules are important because copyrights must be extractable by mechanical means.

- +

Packages distributed under the UCB BSD license, the Artistic license, the GNU GPL, and the GNU LGPL should refer to the diff --git a/upgrading-checklist.html b/upgrading-checklist.html index 8784dbe..91a344b 100644 --- a/upgrading-checklist.html +++ b/upgrading-checklist.html @@ -6,10 +6,10 @@ Author : Manoj Srivastava ( srivasta@tiamat.datasync.com ) Created On : Thu Oct 29 20:54:48 1998 Created On Node : tiamat.datasync.com - Last Modified By : Julian Gilbey - Last Modified On : Mon Jun 19 20:06:50 2000 - Last Machine Used: polya.maths.qmw.ac.uk - Update Count : 11 + Last Modified By : Manoj Srivastava + Last Modified On : Thu Jan 18 01:32:14 2001 + Last Machine Used: glaurung.green-gryphon.com + Update Count : 14 Status : Unknown, Use with caution! HISTORY : Description : @@ -44,10 +44,24 @@ Manual.

The checklist

+3.2.1.1                    Jan 01
+
+  Policy Manual:
+     - If your package has a daemon startup script in /etc/init.d/,
+       and that script has parameters a system administrator may need,
+       you need to modify the script to read values from a conffile
+       placed in /etc/default/ directory. This conffile maybe sourced
+       by the init.d script to determine the sonfigurable values (and
+       the conffile may contain only variable settings and comments).
+     - Files in /usr/share/doc may not be referenced by any
+       program. If such files are needed, they must be placed in
+       /usr/share/package-name/, and symbolic links created as required
+       in /usr/share/doc/package-name/
+
 3.2.1.0                    Aug 00
 
   Policy Manual:
-     - A package of priority standard or hihger may provide two
+     - A package of priority standard or higher may provide two
        binaries, one compiled with support for the X Window System,
        and the other without.
      -
-- 
2.39.5