First draft of review of policy must usage
Hi,
Here is a first draft of changes to the policy that I think
are required to bring ot closer in line with extant practice. I
removed portions from the policy that linked policy violations to bug
severities, since this has been deemed controversial and a "bug" in
policy. Next, I removed the DFSG text and replaced it by a pointer
to the DFSG document itself, this prevents duplication, and I am not
sure I would have remembered to edit it here if we ever changed the
DFSG.
Next, I removed clauses that said that all the requirements of
policy must be met for a package to be in main or contrib; we know
that is not true.
I have replaced some uses of the word must when it was
intended to be non-normative with alternate and equivalent wording,
which makes it easier to grep for "must". This still needs to be
done for should (which I often replace with 'ought to').
Finally, for your review, are some downgrades from must to
should, which bring the document close to the release policy (though
I think the release policy is not exhaustive [one must not ignore
errors in maintainer scripts, and stop installation if needed,
according to policy, but that is not an RC bug, various and sundry
must directives in the package name area, and others], and may in
itself be buggy).
If you have objections to or comments on any of these changes,
please quote just the relevant chunk, and explain why you think the
change is not good. Not that any one can change policy at the moment,
but who knows, I may yet in the future be able to change policy
again.
manoj
--- orig/policy.sgml
+++ mod/policy.sgml
@@ -62,7 +62,7 @@
GNU/Linux distribution. This includes the structure and
contents of the Debian archive and several design issues of the
operating system, as well as technical requirements that
- each package must satisfy to be included in the
+ each package needs to satisfy to be included in the
distribution.
</p>
@@ -113,36 +113,6 @@
either. Please see <ref id="pkg-scope"> for more information.
</p>
- <p>
- In the normative part of 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
- distinguish the significance of the various guidelines in
- this policy document. Packages that do not conform to the
- guidelines denoted by <em>must</em> (or <em>required</em>)
- will generally not be considered acceptable for the Debian
- distribution. Non-conformance with guidelines denoted by
- <em>should</em> (or <em>recommended</em>) will generally be
- considered a bug, but will not necessarily render a package
- unsuitable for distribution. Guidelines denoted by
- <em>may</em> (or <em>optional</em>) are truly optional and
- adherence is left to the maintainer's discretion.
- </p>
-
- <p>
- These classifications are roughly equivalent to the bug
- severities <em>serious</em> (for <em>must</em> or
- <em>required</em> directive violations), <em>minor</em>,
- <em>normal</em> or <em>important</em>
- (for <em>should</em> or <em>recommended</em> directive
- violations) and <em>wishlist</em> (for <em>optional</em>
- items).
- <footnote>
- Compare RFC 2119. Note, however, that these words are
- used in a different way in this document.
- </footnote>
- </p>
<p>
Much of the information presented in this manual will be
@@ -327,98 +327,11 @@
<heading>The Debian Free Software Guidelines</heading>
<p>
The Debian Free Software Guidelines (DFSG) form our
- definition of "free software". These are:
- <taglist>
- <tag>Free Redistribution
- </tag>
- <item>
- The license of a Debian component may not restrict any
- party from selling or giving away the software as a
- component of an aggregate software distribution
- containing programs from several different
- sources. The license may not require a royalty or
- other fee for such sale.
- </item>
- <tag>Source Code
- </tag>
- <item>
- The program must include source code, and must allow
- distribution in source code as well as compiled form.
- </item>
- <tag>Derived Works
- </tag>
- <item>
- The license must allow modifications and derived
- works, and must allow them to be distributed under the
- same terms as the license of the original software.
- </item>
- <tag>Integrity of The Author's Source Code
- </tag>
- <item>
- The license may restrict source-code from being
- distributed in modified form <em>only</em> if the
- license allows the distribution of "patch files"
- with the source code for the purpose of modifying the
- program at build time. The license must explicitly
- permit distribution of software built from modified
- source code. The license may require derived works to
- carry a different name or version number from the
- original software. (This is a compromise. The Debian
- Project encourages all authors to not restrict any
- files, source or binary, from being modified.)
- </item>
- <tag>No Discrimination Against Persons or Groups
- </tag>
- <item>
- The license must not discriminate against any person
- or group of persons.
- </item>
- <tag>No Discrimination Against Fields of Endeavor
- </tag>
- <item>
- The license must not restrict anyone from making use
- of the program in a specific field of endeavor. For
- example, it may not restrict the program from being
- used in a business, or from being used for genetic
- research.
- </item>
- <tag>Distribution of License
- </tag>
- <item>
- The rights attached to the program must apply to all
- to whom the program is redistributed without the need
- for execution of an additional license by those
- parties.
- </item>
- <tag>License Must Not Be Specific to Debian
- </tag>
- <item>
- The rights attached to the program must not depend on
- the program's being part of a Debian system. If the
- program is extracted from Debian and used or
- distributed without Debian but otherwise within the
- terms of the program's license, all parties to whom
- the program is redistributed must have the same
- rights as those that are granted in conjunction with
- the Debian system.
- </item>
- <tag>License Must Not Contaminate Other Software
- </tag>
- <item>
- The license must not place restrictions on other
- software that is distributed along with the licensed
- software. For example, the license must not insist
- that all other programs distributed on the same medium
- must be free software.
- </item>
- <tag>Example Licenses
- </tag>
- <item>
- The "GPL," "BSD," and "Artistic" licenses are examples of
- licenses that we consider <em>free</em>.
- </item>
- </taglist>
- </p>
+ definition of "free software". Please refer to
+ <tt><url name="/social_contract"
+ id="http://www.debian.org/social_contract";></tt>
+ for details.
+ </p>
</sect>
<sect id="sections">
@@ -446,10 +359,6 @@
must not be so buggy that we refuse to support them,
and
</item>
- <item>
- must meet all policy requirements presented in this
- manual.
- </item>
</list>
</p>
@@ -469,10 +378,6 @@
must not be so buggy that we refuse to support them,
and
</item>
- <item>
- must meet all policy requirements presented in this
- manual.
- </item>
</list>
</p>
@@ -689,14 +594,14 @@
expect to find on any Unix-like system. If the
expectation is that an experienced Unix person who
found it missing would say "What on earth is going on,
- where is <prgn>foo</prgn>?", it must be an
+ where is <prgn>foo</prgn>?", it is likely to be an
<tt>important</tt> package.<footnote>
This is an important criterion because we are
trying to produce, amongst other things, a free
Unix.
</footnote>
Other packages without which the system will not run
- well or be usable must also have priority
+ well or be usable also have priority
<tt>important</tt>. This does
<em>not</em> include Emacs, the X Window System, TeX
or any other large applications. The
@@ -733,7 +638,7 @@
</p>
<p>
- Packages must not depend on packages with lower priority
+ Packages should not depend on packages with lower priority
values (excluding build-time dependencies). In order to
ensure this, the priorities of one or more packages may need
to be adjusted.
@@ -986,7 +891,7 @@
particular version of that package.<footnote>
<p>
Essential is defined as the minimal set of functionality
- that must be available and usable on the system even
+ that have to be available and usable on the system even
when packages are in an unconfigured (but unpacked)
state. This is needed to avoid unresolvable dependency
loops on upgrade. If packages add unnecessary
@@ -1002,7 +907,7 @@
<p>
Also, it's pretty unlikely that functionality from
Essential shall ever be removed (which is one reason why
- care must be taken before adding to the Essential
+ care has to be taken before adding to the Essential
packages set), but <em>packages</em> have been removed
from the Essential set when the functionality moved to a
different package. So depending on these packages
@@ -1103,7 +1008,7 @@
<p>
Since these packages cannot be easily removed (one has to
specify an extra <em>force option</em> to
- <prgn>dpkg</prgn> to do so), this flag must not be used
+ <prgn>dpkg</prgn> to do so), this flag ought not be used
unless absolutely necessary. A shared library package
must not be tagged <tt>essential</tt>; dependencies will
prevent its premature removal, and we need to be able to
@@ -1245,7 +1150,7 @@
<p>
If a package has a vitally important piece of
information to pass to the user (such as "don't run me
- as I am, you must edit the following configuration files
+ as I am, you have to edit the following configuration files
first or you risk your system emitting badly-formatted
messages"), it should display this in the
<prgn>config</prgn> or <prgn>postinst</prgn> script and
@@ -1401,11 +1306,10 @@
<heading>Changes to the upstream sources</heading>
<p>
- 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 changes to the source code are made that are not specific
+ to the needs of the Debian system, they ought to 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>
@@ -1642,7 +1546,7 @@
<p>
Every time you put more than one shell command (this
includes using a loop) in a makefile command you
- must make sure that errors are trapped. For
+ 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
@@ -1856,6 +1760,7 @@
level directory.
</p>
+ <!-- Why are we so anal about having these targets?
<p>
Both the <tt>binary-arch</tt> and
<tt>binary-indep</tt> targets <em>must</em> exist.
@@ -1863,6 +1768,18 @@
the case if the source generates only a single binary
package, whether architecture-dependent or not), it
must still exist and must always succeed.
+ -->
+ <p>
+ For arch dependent packages, <tt>binary-arch</tt> must
+ exist, since it is used by the build daemons to auto
+ buld packages. The <tt>binary-indep</tt> target should
+ also exist. If one of them has nothing to do (which
+ will always be the case if the source generates only a
+ single binary package, whether architecture-dependent
+ or not), it can be a no-op. In that case, the no-op
+ target should still be present and should still
+ succeed.
+ </p>
</p>
<p>
@@ -1878,7 +1795,7 @@
<tag><tt>clean</tt></tag>
<item>
<p>
- This must undo any effects that the <tt>build</tt>
+ This should undo any effects that the <tt>build</tt>
and <tt>binary</tt> targets may have had, except
that it should leave alone any output files created in
the parent directory by a run of a <tt>binary</tt>
@@ -1931,7 +1848,7 @@
<p>
The <tt>build</tt>, <tt>binary</tt> and
- <tt>clean</tt> targets must be invoked with the current
+ <tt>clean</tt> targets need to be invoked with the current
directory being the package's top-level directory.
</p>
@@ -2009,7 +1926,7 @@
<p>
The <file>debian/substvars</file> file is usually generated and
modified dynamically by <file>debian/rules</file> targets, in
- which case it must be removed by the <tt>clean</tt> target.
+ which case it should be removed by the <tt>clean</tt> target.
</p>
<p>
@@ -2369,7 +2286,7 @@
If the maintainer's name contains a full stop then the
whole field will not work directly as an email address due
to a misfeature in the syntax specified in RFC822; a
- program using this field as an address must check for this
+ program using this field as an address has to check for this
and correct the problem if necessary (for example by
putting the name in round brackets and moving it to the
end, and bringing the email address forward).
@@ -3195,8 +3112,8 @@
<p>
Additionally, packages interacting with users using
<tt>debconf</tt> in the <prgn>postinst</prgn> script should
- install a <prgn>config</prgn> script in the control area,
- see <ref id="maintscriptprompt"> for details.
+ usually install a <prgn>config</prgn> script in the control
+ area, see <ref id="maintscriptprompt"> for details.
</p>
<p>
@@ -4423,18 +4340,19 @@
<chapt id="sharedlibs"><heading>Shared libraries</heading>
<p>
- Packages containing shared libraries must be constructed with
- a little care to make sure that the shared library is always
- available. This is especially important for packages whose
- shared libraries are vitally important, such as the C library
- (currently <tt>libc6</tt>).
+ Packages containing shared libraries need to be constructed
+ with a little care to make sure that the shared library is
+ always available. This is especially important for packages
+ whose shared libraries are vitally important, such as the C
+ library (currently <tt>libc6</tt>).
</p>
<p>
- Packages involving shared libraries should be split up into
+ Packages involving shared libraries ought to be split up into
several binary packages. This section mostly deals with how
this separation is to be accomplished; rules for files within
- the shared library packages are in <ref id="libraries"> instead.
+ the shared library packages are in <ref id="libraries">
+ instead.
</p>
<sect id="sharedlibs-runtime">
@@ -4722,7 +4640,7 @@
<p>
If a package contains a binary or library which links to a
- shared library, we must ensure that when the package is
+ shared library, we have to ensure that when the package is
installed on the system, all of the libraries needed are
also installed. This requirement led to the creation of the
<tt>shlibs</tt> system, which is very simple in its design:
@@ -4748,7 +4666,7 @@
determined by calling <prgn>ldd</prgn>, but now
<prgn>objdump</prgn> is used to do this. The only
change this makes to package building is that
- <prgn>dpkg-shlibdeps</prgn> must also be run on shared
+ <prgn>dpkg-shlibdeps</prgn> also has to be run on shared
libraries, whereas in the past this was unnecessary.
The rest of this footnote explains the advantage that
this method gives.
@@ -4865,7 +4783,7 @@
determine whether <tt>foo-prog</tt>'s library
dependencies are satisfied by any of the libraries
provided by <tt>libfoo2</tt>. For this reason,
- <prgn>dpkg-shlibdeps</prgn> must only be run once
+ <prgn>dpkg-shlibdeps</prgn> has to be run only once
all of the individual binary packages'
<tt>shlibs</tt> files have been installed into the
build directory.
@@ -6736,10 +6654,10 @@
the LSB anyway.
</footnote>
Thus, shell scripts specifying <file>/bin/sh</file> as
- interpreter must only use POSIX features. If a script
+ interpreter should only use POSIX features. If a script
requires non-POSIX features from the shell interpreter, the
- appropriate shell must be specified in the first line of the
- script (e.g., <tt>#!/bin/bash</tt>) and the package must
+ appropriate shell should be specified in the first line of the
+ script (e.g., <tt>#!/bin/bash</tt>) and the package should
depend on the package providing the shell (unless the shell
package is marked "Essential", as in the case of
<prgn>bash</prgn>).
@@ -6766,7 +6684,7 @@
Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
can be found at <url id="http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/";>.
If an upstream package comes with <prgn>csh</prgn> scripts
- then you must make sure that they start with
+ then you have to make sure that they start with
<tt>#!/bin/csh</tt> and make your package depend on the
<prgn>c-shell</prgn> virtual package.
</p>
@@ -7216,9 +7134,9 @@
<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
+ However, if you do so you have to 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
+ with the rest of the system. You probably ought to
discuss it on <prgn>debian-devel</prgn> first.
</p>
@@ -7245,7 +7163,7 @@
otherwise common directories like <tt>/usr</tt> would
always be in flux. To correctly change permissions of a
directory the package owns, explicit action is required,
- usually in the <tt>postinst</tt> script. Care must be
+ usually in the <tt>postinst</tt> script. Care has to be
taken to handle downgrades as well, in that case.
</p>
</footnote>
@@ -7269,7 +7187,7 @@
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; again there is no point in making
- them unreadable to those users who must not be allowed to
+ them unreadable to those users who are not allowed to
execute them.
</p>
@@ -7376,7 +7294,7 @@
maintainer can use <tt>debconf</tt> to find out the
preference, and call <prgn>dpkg-statoverride</prgn> in the
maintainer script if necessary to accommodate the system
- administrator's choice. Care must be taken during
+ administrator's choice. Care has to be taken during
upgrades to not override an existing setting.
</p>
@@ -9666,7 +9584,7 @@
<p>
As it exists on the FTP site, a Debian source package
- consists of three related files. You must have the right
+ consists of three related files. You need to have the right
versions of all three to be able to use them.
</p>
--
Greener's Law: Never argue with a man who buys ink by the barrel.
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Reply to: