From 1c0ed0f8c1ad9346bea89e7249bd283c042a6e32 Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:39:02 +0000 Subject: [PATCH] formatting fixes; created another administrivia section with a list of links to external sub-policies and the developer's reference (and updated the remaining external references) Author: joy Date: 2003/03/23 17:38:29 formatting fixes; created another administrivia section with a list of links to external sub-policies and the developer's reference (and updated the remaining external references) git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-211 --- policy.sgml | 228 ++++++++++++++++++++-------------------------------- 1 file changed, 87 insertions(+), 141 deletions(-) diff --git a/policy.sgml b/policy.sgml index 940cb09..add3135 100644 --- a/policy.sgml +++ b/policy.sgml @@ -131,6 +131,7 @@ may (or optional) are truly optional and adherence is left to the maintainer's discretion.

+

These classifications are roughly equivalent to the bug severities serious (for must or @@ -138,11 +139,13 @@ normal or important (for should or recommended directive violations) and wishlist (for optional - items). -

Compare RFC 2119. Note, however, that these words are - used in a different way in this document.

+ items). + + Compare RFC 2119. Note, however, that these words are + used in a different way in this document.

+

Much of the information presented in this manual will be useful even when building a package which is to be @@ -226,6 +229,45 @@

+ + Related documents + +

+ There are several other documents other than this Policy Manual + that are necessary to fully understand some Debian policies and + procedures. +

+ +

+ The external "sub-policy" documents are referred to in: + + + + + + + + + +

+ +

+ In addition to those, which carry the weight of policy, there + is the Debian Developer's Reference. This document describes + procedures and resources for Debian developers, but it is + not normative; rather, it includes things that don't + belong into the Policy, such as best practices for developers. +

+ +

+ The Developer's Reference is available in the + developers-reference package. + It's also available from the Debian web mirrors at + . +

+ + @@ -794,17 +836,9 @@ maintainership of the package until someone else volunteers for that task. These packages are called orphaned packages. -

The detailed procedure for doing this gracefully can - be found in the Debian Developer's Reference, either - in the developers-reference package, or on - the Debian FTP server - ftp.debian.org as - /debian/doc/package-developer/developers-reference.txt.gz - or from the webpage. -

+ be found in the Debian Developer's Reference, + see .

@@ -1043,28 +1077,21 @@

- + Prompting in maintainer scripts

Package maintainer scripts may prompt the user if necessary. Prompting may be accomplished by hand -

From the Jasrgon file: by hand 2. By extension, + From the Jargon file: by hand 2. By extension, writing code which does something in an explicit or low-level way for which a presupplied library (debconf, in this instance) routine ought - to have been available.

- (but this is deprecated), or by - communicating though a program, which conforms to the - Debian Configuration management specification, version 2 - or higher (such as debconf). Thiss - specification is included in the - debconf_specification files in the - debian-policy package. You may also - find this file on the FTP site - ftp.debian.org in - /debian/doc/package-developer/debconf_specification.txt.gz - or on your local mirror. + to have been available. + (but this is deprecated), or by communicating + through a program which conforms to the Debian Configuration + management specification, version 2 or higher, such as + debconf

6% of Debian packages [see - + .

+ +

+ 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 + + and from the Debian archive mirrors at + . +

+

Packages which use the Debian Configuration management specification may contain an additional @@ -1103,13 +1142,11 @@ dependencies or pre-dependancies are satisfied. 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 versioned dependencies on it will be satisfied before preconfiguration begins. -

@@ -1199,7 +1236,6 @@ are significant in the Standards-Version control field, and so either these three components or the all four components may be specified. -

In the past, people specified the full version number in the Standards-Version field, for example "2.3.0.0". Since minor patch-level changes don't introduce new @@ -1208,7 +1244,6 @@ specified, in this example "2.3.0". All four components may still be used if someone wishes to do so. -

@@ -1219,11 +1254,9 @@ package complies with the new standards you should update the Standards-Version source package field and release it. -

See the file upgrading-checklist for information about policy which has changed between different versions of this document. -

@@ -1250,7 +1283,7 @@ /usr/share/doc/build-essential/list (which is contained in the build-essential package). -

Rationale: + Rationale: This allows maintaining the list separately @@ -1271,8 +1304,6 @@ the policy management process in the BTS. -

-

@@ -1282,7 +1313,6 @@ build. It is not necessary to list packages which are required merely because some other package in the list of build-time dependencies depends on them. -

The reason for this is that dependencies change, and you should list all those packages, and only those packages that you need directly. What @@ -1294,7 +1324,6 @@ them: installation of libimlib2-dev will automatically ensure that all of its run-time dependencies are satisfied. -

@@ -1667,7 +1696,7 @@ Package: libc6

The upstream_version may contain only alphanumerics -

Alphanumerics are A-Za-z0-9 only.

+ Alphanumerics are A-Za-z0-9 only. and the characters . + - : (full stop, plus, hyphen, colon) and should @@ -1811,14 +1840,12 @@ Package: libc6 Maintainers should preserve the modification times of the upstream source files in a package, as far as is reasonably possible. -

The rationale is that there is some information conveyed by knowing the age of the file, for example, you could recognize that some documentation is very old by looking at the modification time, so it would be nice if the modification time of the upstream source would be preserved. -

@@ -1903,7 +1930,6 @@ Package: libc6 complete. This will ensure that if debian/rules build is run again it will not rebuild the whole program. -

Another common way to do this is for build to depend on build-stamp and to do nothing else, and for the build-stamp @@ -1916,7 +1942,6 @@ Package: libc6 .PHONY target). See the documentation of make for more information on phony targets. -

@@ -1964,11 +1989,9 @@ Package: libc6

The binary targets must be invoked as root. -

The fakeroot package often allows one to build a package correctly even without being root. -

@@ -2093,14 +2116,12 @@ Package: libc6

This file records the changes to the Debian-specific parts of the package -

Though there is nothing stopping an author who is also the Debian maintainer from using it for all their changes, it will have to be renamed if the Debian and upstream maintainers become different people. In such a case, however, it might be better to maintain the package as a non-native package. -

.

@@ -2152,14 +2173,12 @@ Package: libc6 dpkg changelog format (though there is currently only one useful keyword, urgency). -

Recognised urgency values are low, medium, high and emergency. They have an effect on how quickly a package will be considered for inclusion into the testing distribution, and give an indication of the importance of any fixes included in this upload. -

@@ -2178,7 +2197,6 @@ Package: libc6 inclusion of this package into the Debian archive by including the string: closes: Bug#nnnnn in the change details. -

To be precise, the string should match the following Perl regular expression: @@ -2187,7 +2205,6 @@ Package: libc6 Then all of the bug numbers listed will be closed by the archive maintenance script (katie), or in the case of an NMU, marked as fixed. -

@@ -2203,10 +2220,8 @@ Package: libc6

The date should be in RFC822 format -

This is generated by the 822-date program. -

; it should include the time zone specified numerically, with the time zone name or abbreviation optionally present as a comment in parentheses. @@ -2278,14 +2293,12 @@ Package: libc6 It should not exist in a shipped source package, and so it (and any backup files or temporary files such as files.new -

files.new is used as a temporary file by dpkg-gencontrol and dpkg-distaddfile - they write a new version of files here before renaming it, to avoid leaving a corrupted copy if an error - occurs -

+ occurs. ) should be removed by the clean target. It may also be wise to ensure a fresh start by emptying or removing it at the @@ -2327,9 +2340,7 @@ Package: libc6

, device special files, sockets or setuid or setgid files. -

Setgid directories are allowed. -

@@ -2541,13 +2552,11 @@ Package: libc6 should merely do the things that were left undone the first time, if any, and exit with a success status if everything is OK. -

This is so that if an error occurs, the user interrupts dpkg or some other unforeseen circumstance happens you don't leave the user with a badly-broken package when dpkg attempts to repeat the action. -

@@ -3651,14 +3660,12 @@ Replaces: mail-transport-agent librarynamesoversion, where soversion is the version number in the soname of the shared library -

The soname is the shared object name: it's the thing that has to match exactly between building an executable and running it for the dynamic linker to be able run the program. For example, if the soname of the library is libfoo.so.6, the library package would be called libfoo6. -

. Alternatively, if it would be confusing to directly append soversion to libraryname (e.g. because @@ -3706,7 +3713,6 @@ Replaces: mail-transport-agent time that dpkg installs it and the time that ldconfig is run in the postinst script. -

The package management system requires the library to be placed before the symbolic link pointing to it in the .deb file. This is so that when @@ -3724,7 +3730,6 @@ Replaces: mail-transport-agent reorders the files itself as necessary when building a package. Thus it is no longer important to concern oneself with the order of file creation. -

@@ -4023,7 +4028,6 @@ Replaces: mail-transport-agent given the name shlibs. These files give details of any shared libraries included in the package. -

An example may help here. Let us say that the source package foo generates two binary packages, libfoo2 and @@ -4050,7 +4054,6 @@ Replaces: mail-transport-agent all of the individual binary packages' shlibs files have been installed into the build directory. -

@@ -4095,12 +4098,10 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ Otherwise, you will need to explicitly list the compiled binaries and libraries. -

If you are using debhelper, the dh_shlibdeps program will do this work for you. It will also correctly handle multi-binary packages. -

@@ -4161,12 +4162,10 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ dynamic linker, and is usually of the form name.so.major-version, in our example, libz.so.1. -

This can be determined using the command objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME -

The version part is the part which comes after .so., so in our case, it is 1. @@ -4215,10 +4214,8 @@ install -m644 debian/shlibs.package debian/package/DEBIAN/ shlibs file in the control area directly from debian/rules without using a debian/shlibs file at all, -

This is what dh_makeshlibs in the debhelper suite does. -

since the debian/shlibs file itself is ignored by dpkg-shlibdeps. @@ -4309,7 +4306,7 @@ libbar 1 bar1 (>= 1.0-1) Filesystem hierarchy - + Filesystem Structure

@@ -5326,7 +5323,7 @@ Reloading description configuration...done. are kept on the system in this situation.

- + Menus

@@ -5369,7 +5366,7 @@ Reloading description configuration...done.

- + Multimedia handlers

@@ -6410,7 +6407,6 @@ endscript security policy by changing the permissions on a binary: they can do this by using dpkg-statoverride, as described below. -

Ordinary files installed by dpkg (as opposed to conffiles and other similar objects) normally have their permissions reset to the distributed @@ -6420,7 +6416,6 @@ endscript remember to describe dpkg-statoverride in the package documentation; being a relatively new addition to Debian, it is probably not yet well-known. -

Another method you should consider is to create a group for people allowed to use the program(s) and make any setuid @@ -6550,7 +6545,6 @@ done If a program needs to specify an architecture specification string in some place, the following format should be used: arch-os -

The following architectures and operating systems are currently recognised by dpkg-archictecture. The architecture, arch, is one of @@ -6563,7 +6557,6 @@ done linux, gnu, freebsd and openbsd. Use of gnu in this string is reserved for the GNU/Hurd operating system. -

.

@@ -6690,10 +6683,8 @@ done 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. -

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

+ pager program.

@@ -6795,12 +6786,10 @@ http://localhost/doc/package/filename should use fcntl() first and dot locking after this, or alternatively implement the two locking methods in a non blocking way -

If it is not possible to establish both locks, the system shouldn't wait for the second lock to be established, but remove the first lock, wait a (random) time, and start over locking again. -

. Using the functions maillock and mailunlock provided by the liblockfile* @@ -7378,7 +7367,7 @@ name ["syshostname"]: - + Perl programs and modules

@@ -7397,7 +7386,7 @@ name ["syshostname"]:

- + Emacs lisp programs

@@ -7490,7 +7479,6 @@ name ["syshostname"]: maintainer of the package is allowed to write this bug report themselves, if they so desire). Do not close the bug report until a proper manpage is available. -

It is not very hard to write a man page. See the , @@ -7498,7 +7486,6 @@ name ["syshostname"]: created by debmake or dh_make, the helper programs help2man, or the directory /usr/share/doc/man-db/examples. -

@@ -7532,14 +7519,12 @@ name ["syshostname"]: then you should not rely on man finding your manpage under those names based solely on the information in the manpage's header. -

Supporting this in man often requires unreasonable processing time to find a manual page or to report that none exists, and moves knowledge into man's database that would be better left in the filesystem. This support is therefore deprecated and will cease to be present in the future. -

@@ -7617,11 +7602,9 @@ install-info --quiet --remove /usr/share/info/foobar.info Packages must not require the existance of any files in /usr/share/doc/ in order to function -

The system administrator should be able to delete files in /usr/share/doc/ without causing any programs to break. -

. Any files that are referenced by programs but are also useful as standalone documentation should be installed under @@ -7642,9 +7625,9 @@ install-info --quiet --remove /usr/share/info/foobar.info changed to /usr/share/doc/package, and packages must not put documentation in the directory /usr/doc/package. -

At this phase of the transition, we no longer require a + At this phase of the transition, we no longer require a symbolic link in /usr/doc/. At a later point, - policy shall change to make the symbolic links a bug.

+ policy shall change to make the symbolic links a bug.

@@ -7663,11 +7646,9 @@ install-info --quiet --remove /usr/share/info/foobar.info package, in the directory /usr/share/doc/appropriate-package or its subdirectories. -

The rationale: The important thing here is that HTML docs should be available in some package, not necessarily in the main binary package. -

@@ -7771,7 +7752,6 @@ install-info --quiet --remove /usr/share/info/foobar.info in . In non-experimental packages you must use a format for debian/changelog which is supported by the most recent released version of dpkg. -

If you wish to use an alternative format, you may do so as long as you include a parser for it in your source package. The parser must have an API compatible with that expected by @@ -7782,7 +7762,6 @@ install-info --quiet --remove /usr/share/info/foobar.info package. (You will need to agree that the parser and its manpage may be distributed under the GNU GPL, just as the rest of dpkg is.) -

@@ -7806,11 +7785,9 @@ install-info --quiet --remove /usr/share/info/foobar.info naming convention, then this may be achieved either by renaming the files, or by adding a symbolic link, at the maintainer's discretion. -

Rationale: People should not have to look in places for upstream changelogs merely because they are given different names or are distributed in HTML format. -

@@ -7863,11 +7840,9 @@ install-info --quiet --remove /usr/share/info/foobar.info dpkg is a suite of programs for creating binary package files and installing and removing them on Unix systems. -

dpkg is targetted primarily at Debian GNU/Linux, but may work on or be ported to other systems. -

@@ -8093,12 +8068,10 @@ install-info --quiet --remove /usr/share/info/foobar.info It is very important to make these scripts idempotent. -

That means that if it runs successfully or fails and then you call it again it doesn't bomb out, but just ensures that everything is the way it ought to be. -

This is so that if an error occurs, the user interrupts dpkg or some other unforeseen circumstance happens you don't leave the @@ -8185,11 +8158,9 @@ install-info --quiet --remove /usr/share/info/foobar.info

Architecture (mandatory) -

This field should appear in all packages, though dpkg doesn't require it yet so that old packages can still be installed. -

@@ -8233,14 +8204,12 @@ install-info --quiet --remove /usr/share/info/foobar.info times of the upstream source files in a package, as far as is reasonably possible. -

The rationale is that there is some information conveyed by knowing the age of the file, for example, you could recognize that some documentation is very old by looking at the modification time, so it would be nice if the modification time of the upstream source would be preserved. -

@@ -8403,10 +8372,8 @@ install-info --quiet --remove /usr/share/info/foobar.info permissions and ownerships set and the package is constructed using dpkg-deb/ -

This is so that the control file which is produced has the right permissions -

.

@@ -9069,13 +9036,11 @@ install-info --quiet --remove /usr/share/info/foobar.info This file records the changes to the Debian-specific parts of the package -

Though there is nothing stopping an author who is also the Debian maintainer from using it for all their changes, it will have to be renamed if the Debian and upstream maintainers become different people. -

.

@@ -9143,10 +9108,8 @@ install-info --quiet --remove /usr/share/info/foobar.info

The date should be in RFC822 format -

This is generated by the 822-date program. -

; it should include the timezone specified numerically, with the timezone name or abbreviation optionally present as a comment. @@ -9341,14 +9304,12 @@ install-info --quiet --remove /usr/share/info/foobar.info (and any backup files or temporary files such as files.new -

files.new is used as a temporary file by dpkg-gencontrol and dpkg-distaddfile - they write a new version of files here before renaming it, to avoid leaving a corrupted copy if an error occurs -

) should be removed by the clean target. It may also be wise to ensure a fresh start by emptying or removing it at the @@ -9566,24 +9527,18 @@ install-info --quiet --remove /usr/share/info/foobar.info

The source package may not contain any hard links -

This is not currently detected when building source packages, but only when extracting them. -

-

Hard links may be permitted at some point in the future, but would require a fair amount of work. -

, device special files, sockets or setuid or setgid files. -

Setgid directories are allowed. -

@@ -9611,12 +9566,10 @@ install-info --quiet --remove /usr/share/info/foobar.info

Removing files, directories or symlinks. -

Renaming a file is not treated specially - it is seen as the removal of the old file (which generates a warning, but is otherwise ignored), - and the creation of the new - one.

+ and the creation of the new one.

@@ -9725,23 +9678,23 @@ install-info --quiet --remove /usr/share/info/foobar.info the alphanumerics and + - . (plus, minus and full stop). -

The characters @ : = % _ (at, colon, equals, percent and underscore) used to be legal and are still accepted when found in a package file, but may not be - used in new packages -

+ used in new packages.

They must be at least two characters and must start with an alphanumeric. In current versions of dpkg they are - sort of case-sensitive

This is a - bug.

; use lowercase package names unless + sort of case-sensitive + This is a bug. + ; use lowercase package names unless the package you're building (or referring to, in other - fields) is already using uppercase.

+ fields) is already using uppercase. +

Version @@ -9853,10 +9806,8 @@ install-info --quiet --remove /usr/share/info/foobar.info Packages file) it may be followed by a version number in parentheses. -

It is usual to leave a space after the package name if a version number is specified. -

This version number may be omitted (and is, by dpkg-gencontrol) if it has the same value as the Version field of the binary package in @@ -9989,9 +9940,7 @@ install-info --quiet --remove /usr/share/info/foobar.info The syntax is a list of binary packages separated by commas. -

A space after each comma is conventional. -

Currently the packages must be separated using only spaces in the .changes file.

 @@ -10030,10 +9979,7 @@ install-info --quiet --remove /usr/share/info/foobar.info tarfile and (if applicable) diff file which make up the remainder of the source package. -

- That is, the parts which are not the - .dsc. -

+ That is, the parts which are not the .dsc. The exact forms of the filenames are described in .

-- 2.39.5