From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:10:54 +0000 (+0000) Subject: Finished chapter 2 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=843d897b69eb627f48f4df3c5cd7d99b7e424eb4;p=debian%2Fdebian-policy.git Finished chapter 2 Author: jdg Date: 2001/04/12 10:57:25 Finished chapter 2 git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-91 --- diff --git a/debian/changelog b/debian/changelog index 71830ee..ca4673b 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,6 +1,7 @@ debian-policy (3.5.2.1) unstable; urgency=low - * Removed recommendation on packaging-manual closes: Bug#86507 + * Removed recommendation on packaging-manual + closes: Bug#86507, #93620, #93705 * Also now Conflicts and Replaces packaging-manual * Remove FSSTND from binary package, although retain it in the source package for the time being diff --git a/policy.sgml b/policy.sgml index 8585882..ecf7ca0 100644 --- a/policy.sgml +++ b/policy.sgml @@ -202,12 +202,15 @@ New versions of this document

- The current version of this document is always accessible from the - Debian FTP server ftp.debian.org as - /debian/doc/package-developer/debian-policy.html.tar.gz - or from the - webpage.

+ The current version of this document is always accessible + from the Debian FTP server ftp.debian.org + as + /debian/doc/package-developer/policy.text.gz + (also available from the same directory are several other + formats: policy.html.tar.gz, policy.pdf.gz + and policy.ps.gz) or from the webpage.

In addition, this manual is distributed via the Debian package @@ -825,8 +828,11 @@ archive.

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

+ Package names must consist of lower case letters (a-z), + digits (0-9), plus (+) and minus (-) signs, and periods + (.). They must be at least two characters long and must + contain at least one letter. +

The package name is part of the file name of the @@ -838,29 +844,42 @@ The maintainer of a package

- 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 + Every package must have a Debian 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 distributions.

The maintainer must be specified in the - Maintainer control field with the correct name - and a working email address for the Debian maintainer of - the package. If one person maintains several packages - he/she should try to avoid having different forms of their - name and email address in different Maintainer - fields.

+ Maintainer control field with their correct name + and a working email address. If one person maintains + several packages, he/she should try to avoid having + different forms of their name and email address in + the Maintainer fields of those packages. +

If the maintainer of a package quits from the Debian - project the Debian QA Group - debian-qa@lists.debian.org takes over the + project, "Debian QA Group" + packages@qa.debian.org takes over the 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. +

+

@@ -873,15 +892,15 @@ stored in the appropriate field of the control record.

- 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 should not be included -- that is what - installation scripts, manual pages, Info files, etc. are - for. Copyright statements and other administrivia should - not be included -- that is what the copyright file is - for.

+ The description should be written so that it gives the + system administrator enough information to decide whether + to install the package. This description should not just + be copied verbatim from the program's documentation. + Instructions for configuring 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 should not be included + either -- that is what the copyright file is for.

@@ -921,13 +940,13 @@ Virtual packages

- Sometimes, there are several packages doing more-or-less - the same job. In this case, it's useful to define a - virtual package whose name describes the function - the packages have. (The virtual packages just exist - logically, not physically--that's why they are called - virtual.) The packages with this particular - function will then provide the virtual + Sometimes, there are several packages which offer + more-or-less the same functionality. In this case, it's + useful to define a virtual package whose name + describes that common functionality. (The virtual + packages only exist logically, not physically--that's why + they are called virtual.) The packages with this + particular function will then provide the virtual package. Thus, any other package requiring that function can simply depend on the virtual package without having to specify all possible packages individually.

@@ -983,11 +1002,11 @@ for a system.

- Since these packages can not easily be removed (you'll - have to specify an extra force option to - dpkg) this flag must not be used unless - absolutely necessary. A shared library package must not - be tagged essential--the dependencies will + Since these packages cannot be easily removed (one has to + specify an extra force option to + dpkg to do so), this flag must not be used + unless absolutely necessary. A shared library package + must not be tagged essential--dependencies will prevent its premature removal, and we need to be able to remove it when it has been superseded.

@@ -995,7 +1014,7 @@

Since dpkg will not prevent upgrading of other packages while an essential package is in an unconfigured - state, all essential packages must supply all + state, all essential packages must supply all of their core functionality even when unconfigured. If the package cannot satisfy this requirement it must not be tagged as essential, and any packages depending on this @@ -1006,9 +1025,10 @@

You must not tag any packages essential before this has been discussed on the debian-devel - mailing and a consensus about doing that has been - reached.

- + mailing list and a consensus about doing that has been + reached. +

+ Maintainer scripts @@ -1028,7 +1048,7 @@

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

@@ -1048,7 +1068,8 @@ 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). + the usual rule that versioned conflicts should be + avoided).

@@ -1060,21 +1081,22 @@ communicating with a program, such as debconf, which conforms to the Debian Configuration management specification, version 2 or - higher. (Included in the + higher. These are included in the debconf_specification files in the - debian-policy package.) + 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 your local mirror. + or on your local mirror.

- 2.5% of Debian packages - [] - use debconf to prompt the user at install time, and - this number is growing daily. The benefits of using - debconf are briefly explained at - ; + 2.5% of Debian packages [see ] + currently use debconf to prompt + the user at install time, and this number is growing + daily. The benefits of using debconf are briefly + explained at ; they include preconfiguration, (mostly) noninteractive installation, elimination of redundant prompting, consistency of user interface, @@ -1082,12 +1104,13 @@

With this increasing number of packages using - debconf, plus the existance of a nascent second - implementation of the Debian configuration - management system (cdebconf), and - the stabalization of the protocol these things use, - the time has finally come to reflect the use of - these things in policy. + debconf, plus the existance of a + nascent second implementation of the Debian + configuration management system + (cdebconf), and the stabalization + of the protocol these things use, the time has + finally come to reflect the use of these things in + policy.

@@ -1097,17 +1120,18 @@ specification may contain an additional config script and a templates file in their control archive. The config - script can be run before the preinst, and before the - package is unpacked or any of its dependancies or - pre-dependancies are satisfied, so it must work using - only the tools present in the Essential - packages. + script might be run before the preinst + script, and before the package is unpacked or any of its + dependancies 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 dependancies on it will - be satisfied before preconfiguration begins. + 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.

@@ -1118,9 +1142,10 @@ will only ever be asked each question once. This means that packages should try to use appropriate shared configuration files (such as /etc/papersize and - /etc/news/server), and shared debconf variables - rather than each prompting for their own list of - required pieces of information. + /etc/news/server), and shared + debconf variables rather than each + prompting for their own list of required pieces of + information.

@@ -1144,7 +1169,7 @@ important (they belong in /usr/share/doc/package/copyright); neither do instructions on how to use a program (these - should be in on line documentation, where all the users + should be in on-line documentation, where all the users can see them).

@@ -1166,22 +1191,21 @@ Standards conformance

- You should specify the most recent version of the - packaging standards with which your package complies in - the source package's Standards-Version field.

- -

- This value will be used to file bug reports automatically - if your package becomes too much out of date.

+ In the source package's Standards-Version control + field, you must specify the most recent version number of + this policy document with which your package complies. + The current version number is &version;. +

- The value corresponds to a version of the Debian manuals, - as can be found on the title page or page headers and - footers (depending on the format).

+ This information may be used to file bug reports + automatically if your package becomes too much out of + date. +

The version number has four components--major and minor - number and major and minor patch level. When the + version number and major and minor patch level. When the standards change in a way that requires every package to change the major number will be changed. Significant changes that will require work in many packages will be @@ -1189,22 +1213,24 @@ level will be changed for any change to the meaning of the standards, however small; the minor patch level will be changed when only cosmetic, typographical or other edits - which do not change the meaning are made, or changes which - do not affect the contents of packages.

+ are made which neither change the meaning of the document + nor affect the contents of packages.

- 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 may be specified. + Thus only the first three components of the policy version + 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 4 digits in the - Standards-Version field, like `2.3.0.0'. Since any - `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 may still be used if someone wants to do so.) + 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 + policy, it was thought it would be better to relax + policy and only require the first 3 components to be + specified, in this example `2.3.0'. All four + components may still be used if someone wishes to do + so.

@@ -1215,7 +1241,16 @@ available and update your package, if necessary. When your package complies with the new standards you should update the Standards-Version source package field and - release it.

 + release it. + +

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

+ +

+ @@ -1246,23 +1281,24 @@

This allows maintaining the list separately from the policy documents (the list does not need the kind of control that the policy - documents do) + documents do).

Having a separate package allows one to install - the build essential packages on a machine, as - well as allowing other packages (think task - packages) to bring in the build-essential - packages using the depends relation + the build-essential packages on a machine, as + well as allowing other packages such as task + packages to require installation of the + build-essential packages using the depends + relation.

The separate package allows bug reports against - the package to be categorized separately from - the policy management process that uses the BTS + the list to be categorized separately from + the policy management process in the BTS.

@@ -1276,42 +1312,56 @@ should list only those packages explicitly required by the 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 is - that dependencies change, and you should list only those - you need. What others need is their business. + 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 + others need is their business. For example, if you + only link against libimlib, you will need to + build-depend on libimlib2-dev but + not against any libjpeg* packages, even + though libimlib2-dev currently depends on + them: installation of libimlib2-dev + will automatically ensure that all of its run-time + dependencies are satisfied. +

+

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 - relationships are properly satisfied. + on a system with only essential and build-essential + packages installed and also those required to satisfy the + build-time relationships (including any implied + relationships). In particular, this means that version + clauses should be used rigorously in build-time + relationships so that one cannot produce bad or + inconsistently configured packages when the relationships + are properly satisfied.

Changes to the upstream sources

- If changes to the source code are made that are generally - 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 changes to the source code are made that are not + specific to the needs of the Debian system, 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, 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 - override the default in your debian/rules or - wherever is appropriate.

+ provide a way to do so, 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 override the default in your + debian/rules or wherever is appropriate.

You should make sure that the configure utility @@ -1336,20 +1386,31 @@ 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)

+ making a new changelog entry rather than "rewriting history" + by editing old changelog entries.)

- In non-experimental packages you must only use a format for + In non-experimental packages you must 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 - it you should contact the dpkg maintainer to - have the parser script for your format included in the - dpkg 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.)

 + 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 + dpkg-genchanges and + dpkg-gencontrol. If there is general + interest in the new format, you should contact the + dpkg maintainer to have the parser + script for it included in the dpkg + 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.) +

+ +

+ @@ -1357,8 +1418,8 @@

When make invokes a command in a makefile - (including your package's upstream makefiles and the - debian/rules) it does so using sh. This + (including your package's upstream makefiles and + debian/rules), it does so using sh. This means that sh's usual bad error handling properties apply: if you include a miniature script as one of the commands in your makefile you'll find that if you @@ -1391,9 +1452,10 @@ only available in binary form).

- Debian packages should be ported to include - <stdarg.h> and ncurses when - they are built.

+ Debian packages should be patched to use + <stdarg.h> and ncurses + instead. +