Hello world,
As you may or may not've noticed from postings to -devel, I'm on a crusade
against the `important' severity as it stands. The best use I can see
for it is as a measure of severe policy non-compliance, since grave and
critical already exist for packages that are completely unusable for
one reason or another.
So as such, I'd like the following to happen:
* policy be more explicit about what items are considered important
enough to file important bugs against (or remove offending packages)
* lintian be changed so it outputs something more like:
E: copyright-missing
W: manpage-missing
E? insecure-handling-of-/tmp-in-postinst
W? update-rc.d-called-twice-in-postinst
where E/W indicated an important/normal problem, and
:/? indicated a definite/possible problem. RC bugs should
probably be automatically filed on E: errors, then.
* bugs.debian.org &c to clarify the definition of "important"
* people remember that "normal" bugs are important too, and
ideally not so much of the freeze happen with an
"important-only" qualifier.
That's my agenda, anyway. They can probably all be considered separately,
and the one I'm asking y'all to consider now is the first one.
I'd like -policy to take a leaf out of the RFCs and use MUST, SHOULD
and MAY to indicate the severity of requirements, although on a slightly
different metric to that which the RFCs use (not implementing a SHOULD
in an RFC isn't necessarily a bug, and not implementing a MUST may not
be a truly severe bug, either). In particular, MUST/SHOULD/MAY seem like
they'd nicely match important/normal/wishlist.
A first draft of the sort of change I'd like, follows. It includes some
minor fixups and some recent policy additions that I couldn't resist
changing. Sorry.
It's probably more important to get the MUST/SHOULD/MAY thing happening
than worrying too much about whether individual things should be MUST
or SHOULD. They can always be changed later.
Comments, seconds, changes, etc appreciated. (I am following this list,
btw)
--- policy-old.sgml Fri Apr 28 14:15:21 2000
+++ policy.sgml Fri Apr 28 18:49:09 2000
@@ -113,12 +113,22 @@
each package must satisfy to be included in the
distribution.
</p>
+ <p>
+ In this manual, the words <em>must</em>, <em>should</em>,
+ and <em>may</em> and the adjectives <em>required</em>,
+ <em>recommended</em> and <em>optional</em> are used to
+ denote the significance of each particular requirement of
+ Debian policy, as follows. Except in exceptional
+ circumstances, bugs may be filed against packages not
+ adhering to a particular policy requirement with a severity
+ of <em>important</em>, <em>normal</em> or <em>wishlist</em>,
+ respectively.
<p>
This manual does <em>not</em> describe the technical
mechanisms involved in package creation, installation, and
removal. This information can be found in the <em>Debian
Packaging Manual</em> and the <em>Debian System
- Administrators' Manual</em>.
+ Administrators' Manual</em>.
</p>
<p>
This document assumes familiarity with these other two
@@ -330,7 +340,7 @@
<sect1>
<heading>The main section</heading>
<p>
- Every package in "main" must comply with the DFSG (Debian
+ Every package in "main" <em>must</em> comply with the DFSG (Debian
Free Software Guidelines).</p>
<p>
@@ -338,20 +348,20 @@
<list compact="compact">
<item>
<p>
- must not require a package outside of "main" for
- compilation or execution (thus, the package may not
+ <em>must</em> not require a package outside of "main" for
+ compilation or execution (thus, the package <em>must not</em>
declare a "Depends" or "Recommends" relationship on a
non-main package),
</p>
</item>
<item>
<p>
- must not be so buggy that we refuse to support them,
+ should not be so buggy that we refuse to support them,
</p>
</item>
<item>
<p>
- must meet all policy requirements presented in this
+ should meet all policy requirements presented in this
manual.
</p>
</item>
@@ -361,7 +371,7 @@
<sect1>
<heading>The contrib section</heading>
<p>
- Every package in "contrib" must comply with the DFSG.
+ Every package in "contrib" <em>must</em> comply with the DFSG.
</p>
<p>
@@ -390,29 +400,29 @@
the DFSG or which are encumbered by patents or other legal
issues that make their distribution problematic.</p>
<p>
- All packages in `non-free' must be electronically
+ All packages in `non-free' <em>must</em> be electronically
distributable across international borders.
</p>
</sect1>
<sect1>
<heading>The non-us server</heading>
<p>
- Some programs with cryptographic program code must be stored
- on the "non-us" server because of export restrictions of the
- U.S.</p>
+ Some programs with cryptographic program code need to be
+ stored on the "non-us" server because of export restrictions
+ of the U.S.</p>
<p>
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.
</p>
</sect1>
<sect1>
<heading>Further copyright considerations</heading>
<p>
- Every package must be accompanied by a verbatim copy of its
+ Every package <em>must</em> be accompanied by a verbatim copy of its
copyright and distribution license in the file
/usr/share/doc/<package-name>/copyright (see <ref
id="copyrightfile"> for details).</p>
@@ -449,15 +459,14 @@
Programs whose authors encourage the user to make donations
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).</p>
+ unethical, illegal or something similar; otherwise they <em>must</em>
+ go in non-free.</p>
<p>
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
- placed on the Debian FTP site and its mirrors at all.</p>
+ and where no special permission has been obtained, <em>must not</em>
+ be placed on the Debian FTP site and its mirrors at all.</p>
<p>
Note, that under international copyright law (this applies
@@ -480,7 +489,7 @@
<p>
When in doubt, send mail to
- <email>debian-devel@lists.debian.org</email>. Be prepared
+ <email>debian-legal@lists.debian.org</email>. Be prepared
to provide us with the copyright statement. Software
covered by the GPL, public domain software and BSD-like
copyrights are safe; be wary of the phrases `commercial use
@@ -510,7 +519,7 @@
<heading>Priorities</heading>
<p>
- Each package is given a certain <em>priority</em> value,
+ Each package <em>must</em> have a <em>priority</em> value,
which is included in the package's <em>control
record</em>. This information is used in the Debian package
management tool to separate high-priority packages from
@@ -571,7 +580,9 @@
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.</p>
+ distribution, and many applications. Note that optional
+ packages should not conflict with each other.
+ </p>
</item>
<tag><tt>extra</tt></tag>
<item>
@@ -586,7 +597,7 @@
</taglist></p>
<p>
- Packages may not depend on packages with lower priority
+ Packages <em>must not</em> depend on packages with lower priority
values (excluding build-time dependencies). If this does
happen, one of the priority values will have to be adapted.
</p>
@@ -598,7 +609,7 @@
<p>
The Debian GNU/Linux distribution is based on the Debian
package management system, called <prgn>dpkg</prgn>. Thus,
- all packages in the Debian distribution have to be provided
+ all packages in the Debian distribution <em>must</em> be provided
in the <tt>.deb</tt> file format.</p>
@@ -606,12 +617,13 @@
<heading>The package name</heading>
<p>
- Every package must have a name that's unique within the Debian
- archive.</p>
+ Every package <em>must</em> have a name that's unique
+ within the Debian archive.</p>
<p>
- Package names may only consist of lower case letters, digits (0-9),
- plus (+) or minus (-) signs, and periods (.).</p>
+ Package names <em>must</em> only consist of lower case letters,
+ digits (0-9), plus (+) or minus (-) signs, and periods
+ (.).</p>
<p>
The package name is part of the file name of the
@@ -624,13 +636,12 @@
<heading>The maintainer of a package</heading>
<p>
- Every package must 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.</p>
+ Every package <em>must</em> have a maintainer. This person
+ or group is responsible for the package and should ensure
+ that it is policy compliant.</p>
<p>
- The maintainer must be specified in the
+ The maintainer <em>must</em> be specified in the
<tt>Maintainer</tt> control field with the correct name
and a working email address for the Debian maintainer of
the package. If one person maintains several packages
@@ -653,17 +664,17 @@
<heading>The description of a package</heading>
<p>
- Every Debian package must have an extended description
+ Every Debian package <em>must</em> have an extended description
stored in the appropriate field of the control record.</p>
<p>
- 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 also
not be included -- that is what the copyright file is
for.</p>
</sect1>
@@ -673,28 +684,27 @@
<heading>Dependencies</heading>
<p>
- Every package has to specify the dependency information
- about other packages, that are required for the first to
- work correctly.</p>
+ Every package <em>must</em> specify the other packages that are
+ required for the first to work correctly.</p>
<p>
- For example, for any shared libraries required by
- dynamically-linked executable binary in a package a
- dependency entry has to be provided.</p>
+ For example, a dependency entry has to be provided for any
+ shared libraries required by dynamically-linked executable
+ binary in a package .</p>
<p>
- It is not necessary for other packages to declare any
- dependencies they have on other packages which are marked
- <tt>Essential</tt> (see below).</p>
+ It is not required for other packages to declare any
+ (unversioned) dependencies they have on other packages
+ which are marked <tt>Essential</tt> (see below).</p>
<p>
Sometimes, a package requires another package to be
installed <em>and</em> configured before it can be
- installed. In this case, you'll have to specify a
- <tt>Pre-Depends</tt> entry for the package.</p>
+ installed. In this case, the package <em>must </em> specify a
+ <tt>Pre-Depends</tt> entry for the other package.</p>
<p>
- You must not specify a <tt>Pre-Depends</tt> entry for a
+ You should not specify a <tt>Pre-Depends</tt> entry for a
package before this has been discussed on the
<tt>debian-devel</tt> mailing list and a consensus about
doing that has been reached.</p></sect1>
@@ -706,7 +716,7 @@
<p>
Sometimes, there are several packages doing more-or-less
the same job. In this case, it's useful to define a
- <em>virtual package</em> who's name describes the function
+ <em>virtual package</em> whose name describes the function
the packages have. (The virtual packages just exist
logically, not physically--that's why they are called
<em>virtual</em>.) The packages with this particular
@@ -716,9 +726,9 @@
specify all possible packages individually.</p>
<p>
- 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.</p>
@@ -745,14 +755,14 @@
disk usage very small.</p>
<p>
- Most of these packages should have the priority value
+ Most of these packages will have the priority value
<tt>required</tt> or at least <tt>important</tt>, and many
of them will be tagged <tt>essential</tt> (see below).</p>
<p>
- You must not place any packages into the <tt>base</tt>
+ You <em>must not</em> place any packages into the <tt>base</tt>
section before this has been discussed on the
- <tt>debian-devel</tt> mailing list and a consensus about
+ <tt>debian-boot</tt> mailing list and a consensus about
doing that has been reached.</p></sect1>
@@ -768,16 +778,16 @@
<p>
Since these packages can not easily be removed (you'll
have to specify an extra <em>force option</em> to
- <prgn>dpkg</prgn>) this flag must only be used where
+ <prgn>dpkg</prgn>) this flag <em>must</em> only be used where
absolutely necessary.
- A shared library package must not be tagged
+ A shared library package <em>must not</em> be tagged
<em>essential</em>--the dependencies will prevent its
premature removal, and we need to be able to remove it
when it has been superseded.</p>
<p>
- You must not tag any packages <tt>essential</tt> before
+ You <em>must not</em> tag any packages <tt>essential</tt> before
this has been discussed on the <tt>debian-devel</tt>
mailing and a consensus about doing that has been
reached.</p></sect1>
@@ -787,7 +797,7 @@
<heading>Maintainer scripts</heading>
<p>
- 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 <prgn>dpkg</prgn> to stave off boredom on
the part of a user installing many packages. This means,
@@ -845,20 +855,22 @@
package maintainer scripts, too.</p>
<p>
- Do not use <prgn>dpkg-divert</prgn> on a file belonging to
- another package without consulting the maintainer of that
- package first.</p>
-
- <p>
- In order for <prgn>update-alternatives</prgn> 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 <tt>Conflicts</tt> to force the
- De-installation of other packages supplying it which do not
- (yet) use <prgn>update-alternatives</prgn>. 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.</p>
+ You should not use <prgn>dpkg-divert</prgn> on a file
+ belonging to another package without consulting the
+ maintainer of that package first.</p>
+
+ <p>
+ All packages which supply an instance of a `shared'
+ command name (or, in general, filename) should generally
+ use <prgn>update-alternatives</prgn> so that they may be
+ installed together. If <prgn>update-alternatives</prgn> is
+ <em>not</em> used, then each package <em>must</em> use
+ <tt>Conflicts</tt> to ensure that other packages are
+ de-installed. (It may in this case be appropriate to
+ specify a conflict on earlier versions of something that
+ previously did not use
+ <prgn>update-alternatives</prgn>--this is an exception to
+ the usual rule that this is not allowed.</p>
</sect1>
</sect>
<sect>
@@ -898,8 +910,7 @@
For package maintainers, only the first 3 digits of the
manual version are significant in representing the
<em>Standards-Version</em>, 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.
<footnote>
<p>
In the past, people specified 4 digits in the
@@ -907,7 +918,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.)
</p>
</footnote>
</p>
@@ -916,24 +927,26 @@
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
- <tt>Standards-Version</tt> source package field and
- release it.</p></sect1>
+ package complies with the new standards you should update
+ the <tt>Standards-Version</tt> source package field and
+ release it.
+ </p>
+ </sect1>
<sect1>
<heading>Package relationships</heading>
<p>
- 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.
</p>
<p>
- It will not be necessary to explicitly specify build-time
+ It is not 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
@@ -941,7 +954,6 @@
an informational list can be found in
<tt>/usr/share/doc/build-essential/list</tt> (which is
contained in the <tt>build-essential</tt> package).
-
</p>
<p>
@@ -955,17 +967,16 @@
</p>
<p>
- 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
- 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.
+ It build-time dependencies are specified a package <em>must</em>
+ be able to build the package and produce a working binary
+ package after unpacking a source package on a system with
+ the build-essential packages installed and satisfying the
+ build-time relationships (including the 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.
</p>
<sect1>
@@ -973,25 +984,25 @@
<p>
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.</p>
+ 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.</p>
<p>
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
- <prgn>autoconf</prgn> test or <tt>#define</tt>) 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 <tt>debian/rules</tt> or
- wherever is appropriate.</p>
+ provide a way to configure it the way you need to, you
+ should add such configuration facilities (for example, a
+ new <prgn>autoconf</prgn> test or <tt>#define</tt>) 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 <tt>debian/rules</tt>
+ or wherever is appropriate.</p>
<p>
- Please make sure that the <prgn>configure</prgn> utility
- detects the correct architecture specification string
- (refer to <ref id="arch-spec"> for details).</p>
+ You should make sure that the <prgn>configure</prgn>
+ utility detects the correct architecture specification
+ string (refer to <ref id="arch-spec"> for details).</p>
<p>
If you need to edit a <prgn>Makefile</prgn> where
@@ -1008,8 +1019,9 @@
<heading>Documenting your changes</heading>
<p>
- Document your changes and updates to the source package
- properly in the <tt>debian/changelog</tt> file.</p>
+ You should document your changes and updates to the source
+ package properly in the <tt>debian/changelog</tt>
+ file.</p>
<p>
A copy of the file which will be installed in
@@ -1017,7 +1029,7 @@
in <tt>debian/copyright</tt>.</p>
<p>
- In non-experimental packages you may only use a format for
+ In non-experimental packages you <em>must</em> use a format for
<tt>debian/changelog</tt> which is supported by the most
recent released version of <prgn>dpkg</prgn>. If your
format is not supported and there is general support for
@@ -1046,12 +1058,12 @@
<p>
Every time you put more than one shell command (this
includes using a loop) in a makefile command you
- <em>must</em> make sure that errors are trapped. For
+ should make sure that errors are trapped. For
simple compound commands, such as changing directory and
then running a program, using <tt>&&</tt> rather
than semicolon as a command separator is sufficient. For
more complex commands including most loops and
- conditionals you must include a separate <tt>set -e</tt>
+ conditionals you should include a separate <tt>set -e</tt>
command at the start of every makefile command that's
actually one of these miniature shell scripts.</p></sect1>
@@ -1085,7 +1097,7 @@
<heading>Linux File system Structure</heading>
<p>
- The location of all installed files and directories must
+ The location of all installed files and directories <em>must</em>
comply with the Linux File system Hierarchy Standard
(FHS). The latest version of this document can be found
alongside this manual or on
@@ -1111,7 +1123,7 @@
or by manipulating them in their maintainer scripts.</p>
<p>
- However, the package should create empty directories below
+ However, the package may create empty directories below
<tt>/usr/local</tt> so that the system administrator knows
where to place site-specific files. These directories
should be removed on package removal if they are
@@ -1120,17 +1132,18 @@
<p>
Note, that this applies only to directories <em>below</em>
<tt>/usr/local</tt>, not <em>in</em>
- <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
- itself may only contain the sub-directories listed in
- FHS, section 4.6. However, you may create directories
- below them as you wish. You may not remove any of the
- directories listed in 4.6, even if you created them.</p>
+ <tt>/usr/local</tt>. In the directory <tt>/usr/local</tt>
+ itself packages <em>must</em> only create the sub-directories
+ listed in FHS, section 4.6. However, you may create
+ directories below them as you wish. You <em>must not</em> remove
+ any of the directories listed in 4.6, even if you created
+ them.</p>
<p>
Since <tt>/usr/local</tt> may be mounted read-only from a
- remote server, these directories have to be created and
+ remote server, these directories <em>must</em> be created and
removed by the <tt>postinst</tt> and <tt>prerm</tt>
- maintainer scripts. These scripts must not fail if either
+ maintainer scripts. These scripts <em>must not</em> fail if either
of these operations fail. (In the future, it will be
possible to tell <prgn>dpkg</prgn> not to unpack files
matching certain patterns, so that the directories can be
@@ -1153,21 +1166,21 @@
<p>
If you do create a directory in <tt>/usr/local</tt> for
- local additions to a package, you must ensure that
+ local additions to a package, you should ensure that
settings in <tt>/usr/local</tt> take precedence over the
equivalents in <tt>/usr</tt>.</p>
<p>
However, because '/usr/local' and its contents are for
- exclusive use of the local administrator, a package must
- not rely on the presence or absence of files or
+ exclusive use of the local administrator, a package <em>must
+ not</em> rely on the presence or absence of files or
directories in '/usr/local' for normal operation.</p>
<p>
The <tt>/usr/local</tt> directory itself and all the
- subdirectories created by the package should have
- permissions 2775 (group-writable and set-group-id) and be
- owned by <tt>root.staff</tt>.</p>
+ subdirectories created by the package should (by default)
+ have permissions 2775 (group-writable and set-group-id)
+ and be owned by <tt>root.staff</tt>.</p>
</sect1>
</sect>
@@ -1183,7 +1196,7 @@
globally for use by certain packages. Because some packages
need to include files which are owned by these users or
groups, or need the ids compiled into binaries, these ids
- must be used on any Debian system only for the purpose for
+ <em>must</em> be used on any Debian system only for the purpose for
which they are allocated. This is a serious restriction, and
we should avoid getting in the way of local administration
policies. In particular, many sites allocate users and/or
@@ -1195,9 +1208,9 @@
order--but the behavior should be configurable.</p>
<p>
- No package except <tt>base-passwd</tt> may modify
- <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
- <tt>/etc/group</tt>.</p>
+ Any package other than <tt>base-passwd</tt> <em>must not</em> directly modify
+ <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
+ <tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.</p>
<p>
The UID and GID ranges are as follows:
@@ -1205,12 +1218,11 @@
<tag>0-99:</tag>
<item>
<p>
- Globally allocated by the Debian project, must be the
- same on every Debian system. These ids will appear in
- the <tt>passwd</tt> and <tt>group</tt> files of all
- Debian systems, new ids in this range being added
- automatically as the <tt>base-passwd</tt> package is
- updated.</p>
+ Globally allocated by the Debian project. These ids
+ will appear in the <tt>passwd</tt> and <tt>group</tt>
+ files of all Debian systems. New ids in this range
+ will be added automatically as the <tt>base-passwd</tt>
+ package is updated.</p>
<p>
Packages which need a single statically allocated uid
@@ -1303,9 +1315,9 @@
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 <em>must not</em> be assumed that this
method is being used, and any manipulation of the various
- runlevel behaviours must be performed using
+ runlevel behaviours <em>must</em> be performed using
<prgn>update-rc.d</prgn> as described below and not by
manually installing symlinks. For information on the
implementation details of the other method, implemented in
@@ -1352,12 +1364,12 @@
order to start and stop things in--low-numbered links have
their scripts run first. For example, the <tt>K20</tt>
scripts will be executed before the <tt>K30</tt> scripts.
- This is used when a certain service must be started before
+ This is used when a certain service <em>must</em> be started before
another. For example, the name server <prgn>bind</prgn>
might need to be started before the news server
<prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
access lists. In this case, the script that starts
- <prgn>bind</prgn> should have a lower number than the
+ <prgn>bind</prgn> would have a lower number than the
script that starts <prgn>inn</prgn> so that it runs first:
<example>
/etc/rc2.d/S17bind
@@ -1370,7 +1382,7 @@
<heading>Writing the scripts</heading>
<p>
- Packages can and should place scripts in
+ Packages may place scripts in
<tt>/etc/init.d</tt> to start or stop services at boot
time or during a change of runlevel. These scripts should
be named <tt>/etc/init.d/<var>package</var></tt>, and they
@@ -1397,7 +1409,7 @@
</taglist>
The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
- <tt>force-reload</tt> options must be supported by all
+ <tt>force-reload</tt> options <em>must</em> be supported by all
scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
option is optional.</p>
@@ -1437,7 +1449,7 @@
<heading>Managing the links</heading>
<p>
- A program is provided, <prgn>update-rc.d</prgn>, to handle
+ The program, <prgn>update-rc.d</prgn>, is provided to handle
the it easier for package maintainers to arrange for the
proper creation and removal of
<tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
@@ -1446,8 +1458,8 @@
<tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
<p>
- You should use this script to make changes to
- <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
+ You <em>must</em> use this script to make any necessary changes to
+ <tt>/etc/rc<var>n</var>.d</tt> and <em>must not</em> either
include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
in the actual archive or manually create or remove the
symbolic links in maintainer scripts. (The latter will
@@ -1501,7 +1513,7 @@
which contained scripts which were run once per machine
boot. This has been deprecated in favour of links from
<tt>/etc/rcS.d</tt> to files in <tt>/etc/init.d</tt> as
- described in <ref id="/etc/init.d">. No packages may
+ described in <ref id="/etc/init.d">. Packages <em>must not</em>
place files in <tt>/etc/rc.boot</tt>.</p>
<sect1 id="init.d notes">
@@ -1511,14 +1523,14 @@
<em>Do not</em> include the
<tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
<tt>.deb</tt> file system archive! <em>This will cause
- problems!</em> You should create them with
+ problems!</em> You <em>must</em> create them with
<prgn>update-rc.d</prgn>, as above.</p>
<p>
<em>Do not</em> include the
<tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
<prgn>dpkg</prgn>'s conffiles list! <em>This will cause
- problems!</em> <em>Do</em>, however, treat the
+ problems!</em> You <em>should</em>, however, treat the
<tt>/etc/init.d</tt> scripts as configuration files,
either by marking them as conffiles or managing them
correctly in the maintainer scripts (see
@@ -1614,8 +1626,8 @@
<heading>Cron jobs</heading>
<p>
- Packages may not modify the configuration file
- <tt>/etc/crontab</tt>, nor may they modify the files in
+ Packages <em>must not</em> modify the configuration file
+ <tt>/etc/crontab</tt>, and they <em>must not</em> modify the files in
<tt>/var/spool/cron/crontabs</tt>.</p>
<p>
@@ -1636,14 +1648,14 @@
All files installed in any of these directories have to 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.</p>
+ addition, they <em>must</em> be treated as configuration files.</p>
<p>
If a certain job has to be executed more frequently than
daily, the package should install a file
<tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
the same syntax as <tt>/etc/crontab</tt> and is processed by
- <prgn>cron</prgn> automatically. The file must also be
+ <prgn>cron</prgn> automatically. The file <em>must</em> also be
treated as a configuration file. (Note, that entries in the
<tt>/etc/cron.d</tt> directory are not handled by
<prgn>anacron</prgn>. Thus, you should only use this
@@ -1712,7 +1724,7 @@
</list></p>
<p>
- The following formats must be used</p>
+ The following formats should be used</p>
<p>
<list>
@@ -1756,7 +1768,7 @@
</example>
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
@@ -1768,7 +1780,7 @@
<p>
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:
<example>
Setting <parameter> to `<value>'.
</example></p>
@@ -1801,7 +1813,7 @@
<p>when something is executed.</p>
<p>
- 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
@@ -1834,7 +1846,7 @@
<p>
If you have to print a message that doesn't fit into
- the styles described above, you can use something
+ the styles described above, you should use something
appropriate, but please have a look at the overall
rules listed above.</p></item>
</list></p></sect>
@@ -1908,7 +1920,7 @@
<p>
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 <em>must</em> be configured to
comply with the following guidelines.</p>
<p>
@@ -1945,7 +1957,7 @@
X translations are set up to make KB_Backspace
generate ASCII DEL, and to make KB_Delete generate
<tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
- the `delete character' key). This must be done by
+ the `delete character' key). This <em>must</em> be done by
loading the resources using xrdb on all local X
displays, not using the application defaults, so that
the translation resources used correspond to the
@@ -2031,56 +2043,55 @@
<heading>Environment variables</heading>
<p>
- No program may depend on environment variables to get
+ A program <em>must not</em> 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.)</p>
<p>
- If a program should depend on environment variables for its
- configuration, the program has to 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
- `wrapper' shell script which sets the environment variables
- and calls the original program.</p>
+ If a program usually depend on environment variables for its
+ configuration, the program should to be changed to fall back
+ to a reasonable default configuration if these environment
+ variables are not present. If this cannot be done (e.g., if
+ the source code of a non-free program is not available), the
+ program <em>must</em> be replaced by a small `wrapper' shell script
+ which sets the environment variables if they are not already
+ defined, and calls the original program.</p>
<p>
Here is an example of a wrapper script for this purpose:
<example>
#!/bin/sh
- BAR=/var/lib/fubar
+ BAR=${BAR:-/var/lib/fubar}
export BAR
exec /usr/lib/foo/foo "$@"
</example></p>
<p>
Furthermore, as <tt>/etc/profile</tt> is a configuration
- file of the <prgn>bash</prgn> package, no other package may
- put any environment variables or other commands into that
- file.</p>
+ file of the <prgn>bash</prgn> package, other packages <em>must
+ not</em> put any environment variables or other commands into
+ that file.</p>
</sect>
</chapt>
<chapt>
<heading>Files</heading>
-
<sect>
<heading>Binaries</heading>
<p>
- It is not allowed that two packages install programs with
+ Two packages <em>must not</em> 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 <em>must</em> 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
- not be reached, <em>both</em> programs must be
+ not be reached, <em>both</em> programs <em>must</em> be
renamed.</p>
<p>
@@ -2114,7 +2125,7 @@
<p>
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 (<tt>-O3</tt>, for
example); feel free to use them. Please use good judgment
here. Don't use flags for the sake of it; only use them
@@ -2128,15 +2139,15 @@
<heading>Libraries</heading>
<p>
- All libraries must have a shared version in the lib
+ All libraries <em>must</em> have a shared version in the lib
package and a static version in the lib-dev package. The
- shared version must be compiled with <tt>-fPIC</tt>, and
- the static version must not be. In other words, each
- <tt>*.c</tt> file is compiled twice.</p>
+ shared version <em>must</em> be compiled with <tt>-fPIC</tt>, and
+ the static version <em>must not</em> be. In other words, each
+ <tt>*.c</tt> file will need to be compiled twice.</p>
<p>
- You have to specify the gcc option <tt>-D_REENTRANT</tt>
- when building a library (either static or shared) to make
+ You <em>must</em> specify the gcc option <tt>-D_REENTRANT</tt>
+ when building a library (either static or shared) which makes
the library compatible with LinuxThreads.</p>
<p>
@@ -2183,17 +2194,17 @@
</p>
<p>
- Packages that use libtool to create shared libraries must
+ Packages that use libtool to create shared libraries should
include the <em>.la</em> files in the <em>-dev</em>
packages, with the exception that if the package relies on
libtool's <em>libltdl</em> library, in which case the .la
- files must go in the run-time library package. This is a
+ files <em>must</em> go in the run-time library package. This is a
good idea in general, and especially for static linking
- issues.
+ issues. (Huh?)
</p>
<p>
- Please make sure that you use only released versions of
+ You should 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
@@ -2207,7 +2218,7 @@
<heading>Shared libraries</heading>
<p>
- Packages involving shared libraries should be split up
+ Packages involving shared libraries <em>must</em> be split up
into several binary packages.</p>
<p>
@@ -2231,7 +2242,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 have an exact version
dependency on the runtime library, to make sure that
compilation and linking happens correctly.</p>
@@ -2245,7 +2256,7 @@
<p>
If your package has some run-time support programs which
- use the shared library you must <em>not</em> put them in
+ use the shared library you should 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
@@ -2257,21 +2268,21 @@
<p>
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
<var>soname</var>s at once (so that you don't get filename
clashes if you try to install different versions of the
combined shared libraries package).</p>
<p>
- Follow the directions in the <em>Debian Packaging
+ You should follow the directions in the <em>Debian Packaging
Manual</em> for putting the shared library in its package,
- and make sure you include a <tt>shlibs</tt> control area
+ and you <em>must</em> include a <tt>shlibs</tt> control area
file with details of the dependencies for packages which
use the library.</p>
<p>
- Shared libraries should <em>not</em> be installed
+ Shared libraries should not be installed
executable, since <prgn>ld.so</prgn> does not require this
and trying to execute a shared library results in a core
dump.</p></sect>
@@ -2293,28 +2304,28 @@
<p>
Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
should almost certainly start with <tt>set -e</tt> so that
- errors are detected. Every script <em>must</em> use
+ errors are detected. Every script should use
<tt>set -e</tt> or check the exit status of <em>every</em>
command.</p>
<p>
The standard shell interpreter `<tt>/bin/sh</tt>' may be a
symbolic link to any POSIX compatible shell. Thus, shell
- scripts specifying `<tt>/bin/sh</tt>' as interpreter may
+ scripts specifying `<tt>/bin/sh</tt>' 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.,
- `<tt>#!/bin/bash</tt>') and the package has to depend on
+ should be specified in the first line of the script (e.g.,
+ `<tt>#!/bin/bash</tt>') and the package <em>must</em> depend on
the package providing the shell (unless the shell package
is marked `Essential', e.g., in the case of
<prgn>bash</prgn>).</p>
<p>
- Restrict your script to POSIX features when possible so
- that it may use <tt>/bin/sh</tt> as its interpreter. If
- your script works with <prgn>ash</prgn>, it's probably
- POSIX compliant, but if you are in doubt, use
- <tt>/bin/bash</tt>.</p>
+ You should restrict your script to POSIX features when
+ possible so that it may use <tt>/bin/sh</tt> as its
+ interpreter. If your script works with <prgn>ash</prgn>,
+ it's probably POSIX compliant, but if you are in doubt,
+ use <tt>/bin/bash</tt>.</p>
<p>
Perl scripts should check for errors when making any
@@ -2331,13 +2342,13 @@
or even on <ftpsite>ftp.cpan.org</ftpsite>
<ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
If an upstream package comes with <prgn>csh</prgn> scripts
- then you must make sure that they start with
+ then you <em>must</em> make sure that they start with
<tt>#!/bin/csh</tt> and make your package depend on the
<prgn>c-shell</prgn> virtual package.</p>
<p>
Any scripts which create files in world-writable
- directories (e.g., in <tt>/tmp</tt>) have to use a
+ directories (e.g., in <tt>/tmp</tt>) <em>must</em> use a
mechanism which will fail if a file with the same name
already exists.</p>
@@ -2396,17 +2407,17 @@
<heading>Device files</heading>
<p>
- No package may include device files in the package file
+ Packages <em>must not</em> include device files in the package file
tree.</p>
<p>
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 <em>must</em> call
<prgn>makedev</prgn> in the <tt>postinst</tt> script,
after asking the user for permission to do so.</p>
<p>
- No package should remove any device files in the
+ Packages <em>must not</em> remove any device files in the
<tt>postrm</tt> or any other script. This is left to the
system administrator.</p>
@@ -2460,12 +2471,12 @@
<heading>Location</heading>
<p>
Any configuration files created or used by your package
- should reside in <tt>/etc</tt>. If there are several you
+ <em>must</em> reside in <tt>/etc</tt>. If there are several you
should consider creating a subdirectory of <tt>/etc</tt>
named after your package.</p>
<p>
- If your packages creates or uses configuration files
+ If your package creates or uses configuration files
outside of <tt>/etc</tt>, and it is not feasible to modify
the package to use the <tt>/etc</tt>, you should still put
the files in <tt>/etc</tt> and create symbolic links to
@@ -2476,15 +2487,15 @@
<sect1>
<heading>Behavior</heading>
<p>
- Configuration file handling must conform to the following
+ Configuration file handling <em>must</em> conform to the following
behavior:
<list>
<item>
- <p>local changes must be preserved during a package
+ <p>local changes <em>must</em> be preserved during a package
upgrade</p>
</item>
<item>
- <p>configuration files should be preserved when the
+ <p>configuration files <em>must</em> be preserved when the
package is removed, and only deleted when the
package is purged.</p>
</item>
@@ -2497,33 +2508,34 @@
version that will work for most installations, although
some system administrators may choose to modify it. This
implies that the default version will be part of the
- package distribution, and must not be modified by the
+ package distribution, and <em>must</em> not be modified by the
maintainer scripts during installation (or at any other
time).</p>
<p>
The other way to do it is to via the maintainer scripts.
- In this case, the configuration file must not be listed as
- a <tt>conffile</tt> and must not be part of the package
+ In this case, the configuration file <em>must</em> not be listed as
+ a <tt>conffile</tt> and <em>must</em> not be part of the package
distribution. If the existence of a file is required for
the package to be sensibly configured it is the
responsibility of the package maintainer to write scripts
which correctly create, update, maintain and
- remove-on-purge the file. These scripts must be idempotent
- (i.e. must work correctly if <prgn>dpkg</prgn> needs to
+ remove-on-purge the file. These scripts <em>must</em> be idempotent
+ (i.e. <em>must</em> work correctly if <prgn>dpkg</prgn> needs to
re-run them due to errors during installation or removal),
- must cope with all the variety of ways <prgn>dpkg</prgn>
- can call maintainer scripts, must not overwrite or
+ <em>must</em> cope with all the variety of ways <prgn>dpkg</prgn>
+ can call maintainer scripts, <em>must</em> not overwrite or
otherwise mangle the user's configuration without asking,
- must not ask unnecessary questions (particularly during
+ <em>must</em> not ask unnecessary questions (particularly during
upgrades), and otherwise be good citizens.</p>
<p>
- The scripts need not 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
- (semi-)automatically by the <tt>postinst</tt> script.</p>
+ 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 (semi-)automatically by the
+ <tt>postinst</tt> script.</p>
<p>
A common practice is to create a script called
@@ -2538,8 +2550,8 @@
(<em>not</em> <tt>conffiles</tt>).</p>
<p>
- These two styles of configuration file handling <em>must
- not be mixed</em>, for that way lies madness:
+ These two styles of configuration file handling <em>must</em>
+ not be mixed, for that way lies madness:
<prgn>dpkg</prgn> will ask about overwriting the file
every time the package is upgraded.</p>
</sect1>
@@ -2547,23 +2559,22 @@
<sect1>
<heading>Sharing configuration files</heading>
<p>
- Only packages that are tagged <em>conflicting</em> with
- each other may specify the same file as
+ Packages that are not tagged <em>conflicting</em> with
+ each other <em>must not</em> specify the same file as
<tt>conffile</tt>.</p>
<p>
- The maintainer scripts should not alter the conffile of
- <em>any</em> package, including the one the scripts belong
- to.</p>
+ The maintainer scripts <em>must not</em> alter the conffile of
+ any package, including the one the scripts belong to.</p>
<p>
If two or more packages use the same configuration file
and it is reasonable for both to be installed at the same
- time, one of these packages must be defined as
+ time, one of these packages <em>must</em> be defined as
<em>owner</em> of the configuration file, i.e. it will be
the package to list that distributes the file and lists it
as a <tt>conffile</tt>. Other packages that use the
- configuration file should depend on the owning package if
+ configuration file <em>must</em> 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
@@ -2573,7 +2584,7 @@
If it is desirable for two or more related packages to
share a configuration file <em>and</em> 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:
<enumlist>
<item>
<p>
@@ -2589,7 +2600,7 @@
</item>
<item>
<p>
- the related packages must use the provided program
+ the related packages <em>must</em> use the provided program
to make any modifications to the configuration file.
They should either depend on the core package to
guarantee that the configuration modifier program is
@@ -2621,28 +2632,15 @@
by the package's installation scripts).</p>
<p>
- However, programs that require dotfiles in order to
- operate sensibly (dotfiles that they do not create
- themselves automatically, that is) are a bad thing, and
- programs should be configured by the Debian default
- installation as close to normal as possible.</p>
-
- <p>
- Therefore, if a program in a Debian package needs to be
- configured in some way in order to operate sensibly that
- configuration should be done in a site-wide global
- configuration file elsewhere in <tt>/etc</tt>. 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
- <tt>/etc/skel</tt>.</p>
-
- <p>
- <tt>/etc/skel</tt> should be as empty as we can make it.
- This is particularly true because there is no easy
- mechanism for ensuring that the appropriate dotfiles are
- copied into the accounts of existing users when a package
- is installed.</p>
+ However, programs should not require dotfiles in order to
+ operate sensibly (unless they create the dotfiles
+ themselves automatically, that is).</p>
+
+ <p>
+ (wouldn't it be better to specify that any dotfiles in .skel
+ be nothing more than templates, and that packages <em>must not</em>
+ depend on the dotfiles already being present? ---aj)</p>
+
</sect1>
</sect>
@@ -2667,7 +2665,7 @@
</p>
<p>
- Log files should usually be named
+ Log files should be named
<tt>/var/log/<var>package</var>.log</tt>. If you have many
log files, or need a separate directory for permissions
reasons (<tt>/var/log</tt> is writable only by
@@ -2675,7 +2673,7 @@
<tt>/var/log/<var>package</var></tt>.</p>
<p>
- Make sure that any log files are rotated occasionally so
+ Log files <em>must</em> be rotated occasionally so
that they don't grow indefinitely; the best way to do this
is to drop a script into the directory
<tt>/etc/logrotate.d</tt> and use the facilities provided by
@@ -2699,10 +2697,9 @@
</p>
<p>
- Make sure that any log files are removed when the package is
- purged (but not when it is only removed), by checking the
- argument to the <tt>postrm</tt> script (see the <em>Debian
- Packaging Manual</em> for details).</p>
+ Log files should be removed when the package is
+ purged (but not when it is only removed) (see the <em>Debian
+ Packaging Manual</em> for details on how to achieve this).</p>
</sect>
@@ -2712,8 +2709,8 @@
<p>
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
+ However, if you do so you <em>must</em> make sure that what is done
+ 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 <prgn>debian-devel</prgn> first.</p>
@@ -2745,11 +2742,11 @@
should be owned by the uid to which they are set-id, and
by the group which should be allowed to execute them.
They should have mode 4754; there is no point in making
- them unreadable to those users who must not be allowed to
+ them unreadable to those users who <em>must not</em> be allowed to
execute them.</p>
<p>
- Do not arrange that the system administrator can only
+ You <em>must not</em> 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 <prgn>dpkg</prgn> (as opposed
@@ -2766,30 +2763,30 @@
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.</p>
+ (though this latter should be avoided if possible, as in
+ this case you need a statically allocated id).</p>
<p>
- 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
- system with the id present in <tt>/etc/passwd</tt> or
- <tt>/etc/group</tt>, or alternatively arrange for your
- package to create the user or group itself with the
- correct id (using <tt>adduser</tt>) in its pre- or
- post-installation script (the latter is to be preferred if
- it is possible).</p>
+ If you need a statically allocated id, you <em>must</em> ask for a
+ user or group id from the base system maintainer, but <em>must</em>
+ not release the package until you have been allocated one.
+ Once you have been allocated one you <em>must</em> make the package
+ depend on a version of the base system with the id present
+ in <tt>/etc/passwd</tt> or <tt>/etc/group</tt>, or
+ alternatively arrange for your package to create the user
+ or group itself with the correct id (using
+ <tt>adduser</tt>) in its pre- or post-installation script
+ (the latter is to be preferred if it is possible).</p>
<p>
- On the other hand, the program may able to determine the
+ On the other hand, the program may 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
<prgn>debian-devel</prgn> and checking with the base
system maintainer that it is unique and that they do not
wish you to use a statically allocated id instead. When
- this has been checked you must arrange for your package to
+ this has been checked you <em>must</em> arrange for your package to
create the user or group if necessary using
<prgn>adduser</prgn> in the pre- or post-installation
script (again, the latter is to be preferred if it is
@@ -2812,14 +2809,14 @@
<p>
If a program needs to specify an <em>architecture specification
- string</em> in some place, the following format has to be used:
+ string</em> in some place, the following format should be used:
<example>
<arch>-<os>
</example>
where `<arch>' is one of the following: i386, alpha, arm, m68k,
powerpc, sparc and `<os>' is one of: linux, gnu. Use
of <em>gnu</em> in this string is reserved for the GNU/Hurd
- operating system. .</p>
+ operating system.</p>
<p>
Note, that we don't want to use `<arch>-debian-linux'
to apply to the rule `architecture-vendor-os' since this
@@ -2840,20 +2837,19 @@
<p>
If a package requires a new entry in one of these files, the
- maintainer has to get in contact with the
- <prgn>netbase</prgn> maintainer, who will add the entries
- and release a new version of the <prgn>netbase</prgn>
- package.</p>
+ maintainer should get contact the <prgn>netbase</prgn>
+ maintainer, who will add the entries and release a new
+ version of the <prgn>netbase</prgn> package.</p>
<p>
- The configuration file <tt>/etc/inetd.conf</tt> may be
- modified by the package's scripts only via the
+ The configuration file <tt>/etc/inetd.conf</tt> <em>must not</em> be
+ modified by the package's scripts except via the
<prgn>update-inetd</prgn> script or the
<prgn>DebianNet.pm</prgn> Perl module.</p>
<p>
If a package wants to install an example entry into
- <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
+ <tt>/etc/inetd.conf</tt>, the entry <em>must</em> be preceded by
exactly one hash character (<tt>#</tt>). Such lines are
treated as `commented out by user' by the
<prgn>update-inetd</prgn> script and are not changed or
@@ -2866,15 +2862,15 @@
<p>
Some programs need to create pseudo-ttys. This should be done
using Unix98 ptys if the C library supports it. The resulting
- program must not be installed setuid root, unless that
+ program <em>must not</em> be installed setuid root, unless that
is required for other functionality.
</p>
<p>
The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
- <tt>/var/log/lastlog</tt> must be installed writeable by
- group utmp. Programs who need to modify those files must
- be installed install setgid utmp.
+ <tt>/var/log/lastlog</tt> <em>must</em> be installed writeable by
+ group utmp. Programs who need to modify those files <em>must</em>
+ be installed setgid utmp.
</p>
</sect>
@@ -2887,34 +2883,31 @@
lots of different editors and pagers available in the Debian
distribution, the system administrator and each user should
have the possibility to choose his/her preferred editor and
- pager.</p>
-
- <p>
- In addition, every program should choose a good default
+ pager. In addition, every program should choose a good default
editor/pager if none is selected by the user or system
administrator.</p>
<p>
- Thus, every program that launches an editor or pager has to
+ Thus, every program that launches an editor or pager <em>must</em>
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 <tt>/usr/bin/editor</tt>
- and <tt>/usr/bin/pager</tt> have to be used, respectively.</p>
+ and <tt>/usr/bin/pager</tt> <em>must</em> be used, respectively.</p>
<p>
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 <em>must</em> call the
<prgn>update-alternatives</prgn> script to register these
programs.</p>
<p>
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 <tt>/usr/bin/sensible-editor</tt> and
<tt>/usr/bin/sensible-pager</tt> 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
+ launche the appropriate program or fall back to
<tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
automatically.</p>
@@ -2926,8 +2919,8 @@
<p>
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.</p></sect>
@@ -2935,7 +2928,7 @@
<heading>Web servers and applications</heading>
<p>
- 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.</p>
@@ -2945,11 +2938,11 @@
<p>Cgi-bin executable files are installed in the
directory
<example>
- /usr/lib/cgi-bin/<cgi-bin-name>
+ /usr/lib/cgi-bin/<var>cgi-bin-name</var>;
</example>
- and can be referred to as
+ and should be referred to as
<example>
- http://localhost/cgi-bin/<cgi-bin-name>
+ http://localhost/cgi-bin/<var>cgi-bin-name</var>;
</example></p></item>
@@ -2961,9 +2954,9 @@
be accessed via symlinks as
<tt>/usr/doc/<var>package</var></tt><footnote> for
backward compatibility, see <ref id="usrdoc"></footnote>
- and can be referred to as
+ and should be referred to as
<example>
- http://localhost/doc/<package>/<filename>
+ http://localhost/doc/<var>package</var>/<var>filename</var>
</example></p></item>
@@ -2971,8 +2964,8 @@
<p>
Web Applications should try to avoid storing files in
- the Web Document Root. Instead use the
- /usr/share/doc/<package> directory for documents and
+ the Web Document Root. Instead they should use the
+ /usr/share/doc/<var>package</var>; directory for documents and
register the Web Application via the menu package. If
access to the web-root is unavoidable then use
<example>
@@ -3005,10 +2998,10 @@
<p>
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 <tt>fcntl()</tt> locking has
- to be combined with dot locking. To avoid dead locks, a
- program has to use <tt>fcntl()</tt> first and dot locking
+ programs (like IMAP daemons) <em>must</em> lock the mailbox in a
+ NFS-safe way. This means that <tt>fcntl()</tt> locking <em>must</em>
+ be combined with dot locking. To avoid dead locks, a
+ program <em>must</em> use <tt>fcntl()</tt> first and dot locking
after this or alternatively implement the two locking
methods in a non blocking way<footnote>
<p>
@@ -3021,20 +3014,20 @@
<tt>liblockfile*</tt><footnote>
<p>
<tt>liblockfile</tt> version >>1.01</p>
- </footnote> packages is the recommended way to realize this.
+ </footnote> packages is the easiest way to realize this.
</p>
<p>
Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
unless the user has chosen otherwise. A MUA may remove a
mailbox (unless it has nonstandard permissions) in which
- case the MTA or another MUA must recreate it if needed.
- Mailboxes must be writable by group mail.</p>
+ case the MTA or another MUA <em>must</em> recreate it if needed.
+ Mailboxes <em>must</em> be writable by group mail.</p>
<p>
- The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
+ The mail spool is 2775 <tt>mail.mail</tt>, and MUAs should to
be setgid mail to do the locking mentioned above (and
- obviously need to avoid accessing other users' mailboxes
+ <em>must</em> obviously avoid accessing other users' mailboxes
using this privilege).</p>
<p>
@@ -3042,10 +3035,10 @@
aliases (e.g., postmaster, usenet, etc.)--it is the one
which the sysadmin and <tt>postinst</tt> scripts may edit.
After <tt>/etc/aliases</tt> is edited the program or human
- editing it must call <prgn>newaliases</prgn>. All MTA
- packages should come with a <prgn>newaliases</prgn> program,
- even if it does nothing, but older MTA packages do not do
- this so programs should not fail if <prgn>newaliases</prgn>
+ editing it <em>must</em> call <prgn>newaliases</prgn>. All MTA
+ packages <em>must</em> come with a <prgn>newaliases</prgn> program,
+ even if it does nothing, but as older MTA packages do not do
+ this, programs should not fail if <prgn>newaliases</prgn>
cannot be found.</p>
<p>
@@ -3054,10 +3047,10 @@
supported. Use a <tt>.forward</tt> file instead.</p>
<p>
- The location for the <prgn>rmail</prgn> program used by UUCP
- for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
+ The <prgn>rmail</prgn> program used by UUCP
+ for incoming mail should be <tt>/usr/sbin/rmail</tt>, as per the
FHS. Likewise, <prgn>rsmtp</prgn>, for receiving
- batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
+ batch-SMTP-over-UUCP, should be <tt>/usr/sbin/rsmtp</tt> if it
is supported.</p>
<p>
@@ -3104,7 +3097,7 @@
<taglist>
<tag>/etc/news/organization</tag>
- <item><p>A string which shall appear as the
+ <item><p>A string which should appear as the
organization header for all messages posted
by NNTP clients on the machine</p></item>
@@ -3136,11 +3129,11 @@
not need to install the whole of X.</p>
<p>
- 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.</p>
<p>
- <em>Application defaults</em> files have to be installed in
+ <em>Application defaults</em> files <em>must</em> be installed in
the directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>.
They are considered as part of the program code. Thus, they
should not be modified and should not be tagged as
@@ -3157,12 +3150,12 @@
<tt>/etc/X11/Xresources</tt> <em>file</em>.</p>
<p>
- No package should ever install files into the directories
+ Packages <em>must not</em> install files into the directories
<tt>/usr/bin/X11/</tt>, <tt>/usr/share/doc/X11/</tt>,
<tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>; these
directories are actually symbolic links, which <tt>dpkg</tt>
- does not follow when unpacking a package. Instead, use
- <tt>/usr/X11R6/bin/</tt>, <tt>/usr/share/doc/package/</tt>
+ does not follow when unpacking a package. Instead, a package may use
+ <tt>/usr/X11R6/bin/</tt>, <tt>/usr/share/doc/<var>package</var>/</tt>
(i.e., place files with the rest of your package's
documentation), <tt>/usr/X11R6/include/</tt>, and
<tt>/usr/X11R6/lib/</tt>. This restriction governs only the
@@ -3179,10 +3172,10 @@
If you package a program that requires the (non-free)
OSF/Motif library, you should try to determine whether the
programs works reasonably well with the free
- re-implementation of Motif called LessTif. If so, build the
- package using the LessTif libraries; it can then go into the
- main section of the package repository and become an
- official part of the Debian distribution.</p>
+ re-implementation of Motif called LessTif. If so, you
+ should build the package using the LessTif libraries; it can
+ then go into the main section of the package repository and
+ become an official part of the Debian distribution.</p>
<p>
If however, the Motif-based program works insufficiently
@@ -3200,7 +3193,7 @@
nor "-dmotif" packages can go into the main section; if the
licensing on the package is compatible with the Debian Free
Software Guidelines, it may go into the contrib section;
- otherwise it must go into the non-free section.
+ otherwise it <em>must</em> go into the non-free section.
</p>
</sect>
@@ -3228,11 +3221,11 @@
<p>
Games which require protected, privileged access to
- high-score files, savegames, etc., must be made
+ high-score files, savegames, etc., should be made
set-<em>group</em>-id (mode 2755) and owned by
<tt>root.games</tt>, and use files and directories with
appropriate permissions (770 <tt>root.games</tt>, for
- example). They must <em>not</em> be made
+ example). They <em>must not</em> be made
set-<em>user</em>-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
@@ -3247,7 +3240,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 <tt>.deb</tt> 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
@@ -3270,19 +3263,24 @@
<heading>Manual pages</heading>
<p>
- You must install manual pages in <prgn>nroff</prgn> source
+ You should install manual pages in <prgn>nroff</prgn> source
form, in appropriate places under <tt>/usr/share/man</tt>. You
should only use sections 1 to 9 (see the FHS for more
- details). You must <em>not</em> install a preformatted `cat
+ details). You <em>must not</em> install a preformatted `cat
page'.</p>
<p>
+ Each program, utility, function and configuration file
+ should have an associated manpage included in the same
+ package.
+
+ <p>
If no manual page is available for a particular program,
- utility or function and this is reported as a bug on
- debian-bugs, a symbolic link from the requested manual page
- to the <manref name="undocumented" section="7"> manual page
- should be provided. This symbolic link can be created from
- <tt>debian/rules</tt> like this:
+ 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 <manref name="undocumented" section="7">
+ manual page should be provided. This symbolic link can be
+ created from <tt>debian/rules</tt> like this:
<example>
ln -s ../man7/undocumented.7.gz \
debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
@@ -3310,8 +3308,8 @@
is better to use a symbolic link than the <tt>.so</tt>
feature, but there is no need to fiddle with the relevant
parts of the upstream source to change from <tt>.so</tt> 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, and should not put
absolute filenames in <tt>.so</tt> directives. The filename
in a <tt>.so</tt> in a manpage should be relative to the
base of the manpage tree (usually
@@ -3326,7 +3324,7 @@
They should be compressed with <tt>gzip -9</tt>.</p>
<p>
- Your package must call <prgn>install-info</prgn> to update the Info
+ Your package should call <prgn>install-info</prgn> to update the Info
<tt>dir</tt>
file, in its post-installation script:
<example>
@@ -3346,14 +3344,14 @@
the second is used when creating a new one.</p>
<p>
- You must remove the entries in the pre-removal script:
+ You should remove the entries in the pre-removal script:
<example>
install-info --quiet --remove /usr/share/info/foobar.info
</example></p>
<p>
If <prgn>install-info</prgn> cannot find a description entry
- in the Info file you will have to supply one. See <manref
+ in the Info file you should supply one. See <manref
name="install-info" section="8"> for details.</p>
</sect>
@@ -3361,7 +3359,7 @@
<heading>Additional documentation</heading>
<p>
- 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
<tt>/usr/share/doc/<var>package</var></tt>, where
@@ -3392,13 +3390,13 @@
in <tt>/usr/doc/<var>package</var></tt>. To realize a
smooth migration to
<tt>/usr/share/doc/<var>package</var></tt>, each package
- must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
+ <em>must</em> maintain a symlink <tt>/usr/doc/<var>package</var></tt>
that points to the new location of its documentation in
<tt>/usr/share/doc/<var>package</var></tt><footnote>These
symlinks will be removed in the future, but they have to be
there for compatibility reasons until all packages have
moved and the policy is changed accordingly.</footnote>.
- The symlink must be created when the package is installed;
+ The symlink <em>must</em> be created when the package is installed;
it cannot be contained in the package itself due to problems
with <prgn>dpkg</prgn>. One reasonable way to accomplish
this is to put the following in the package's
@@ -3451,25 +3449,25 @@
<heading>Copyright information</heading>
<p>
- Every package must be accompanied by a verbatim copy of its
+ Every package <em>must</em> be accompanied by a verbatim copy of its
copyright and distribution license in the file
- /usr/share/doc/<package-name>/copyright. This file must
+ /usr/share/doc/<var>package</var>/copyright. This file <em>must</em>
neither be compressed nor be a symbolic link.</p>
<p>
- In addition, the copyright file must say where the upstream
- sources (if any) were obtained, and explain briefly what
+ In addition, the copyright file <em>must</em> say where the upstream
+ 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.</p>
<p>
- /usr/share/doc/<package-name> may be a symbolic link to a
+ /usr/share/doc/<var>package</var> may be a symbolic link to a
directory in /usr/share/doc only if two packages both come from
the same source and the first package has a "Depends"
relationship on the second. These rules are important
- because copyrights must be extractable by mechanical
+ because copyrights <em>must</em> be extractable by mechanical
means.</p>
<p>
@@ -3502,7 +3500,7 @@
</p>
<p>
- Do not use the copyright file as a general <tt>README</tt>
+ You should not use the copyright file as a general <tt>README</tt>
file. If your package has such a file it should be
installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
<tt>README.Debian</tt> or some other appropriate place.</p>
@@ -3529,24 +3527,20 @@
<heading>Changelog files</heading>
<p>
- This installed file must contain a copy of the
- <tt>debian/changelog</tt> 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
- <tt>/usr/share/doc/<var>package</var></tt> as
- <tt>changelog.Debian.gz</tt>. If the upstream changelog
- file is text formatted, it must be accessible as
- <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>. If
- the upstream changelog file is HTML formatted, it must be
- accessible as
- <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>.
- A plain text version of the changelog must be accessible as
- <tt>/usr/doc/<var>package</var>/changelog.gz</tt> (this can
- be created by <tt>lynx -dump -nolist</tt>). 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. </p>
+ Packages that are not Debian-native must contain a copy of
+ the <tt>debian/changelog</tt> file from your Debian source
+ tree, in <tt>/usr/share/doc/<var>package</var></tt> as
+ <tt>changelog.Debian.gz</tt>. If an upstream changelog is
+ available, it should be accessable as
+ <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt> in
+ plain text. If the upstream changelog is distributed in
+ HTML, it should be made available in that form as
+ <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>
+ and the <tt>changelog.gz</tt> should be generated using, eg,
+ <tt>lynx -dump -nolist</tt>. 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. </p>
<p>
Both should be installed compressed using <tt>gzip -9</tt>,
@@ -3556,8 +3550,8 @@
<p>
If the package has only one changelog which is used both as
the Debian changelog and the upstream one because there is
- no separate upstream maintainer then that changelog should
- usually be installed as
+ no separate upstream maintainer then that changelog must
+ be installed as
<tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
there is a separate upstream maintainer, but no upstream
changelog, then the Debian changelog should still be called
@@ -3566,9 +3560,3 @@
</chapt>
</book>
</debiandoc>
-
-
-
-
-
-
--
Anthony Towns <aj@humbug.org.au> <http://azure.humbug.org.au/~aj/>
I don't speak for anyone save myself. GPG encrypted mail preferred.
``We reject: kings, presidents, and voting.
We believe in: rough consensus and working code.''
-- Dave Clark
Attachment:
pgpYkFUxu807h.pgp
Description: PGP signature