Bug#944920: Revise terminology used to specify requirements
Sean Whitton <spwhitton@spwhitton.name> writes:
> On Sun 17 Nov 2019 at 10:10AM -08, Russ Allbery wrote:
>> +* The term *may* and the adjective *optional* are sometimes used to
>> + clarify cases where it may otherwise appear that Policy is specifying a
>> + requirement or recommendation. These words describe decisions that are
>> + truly optional and at the maintainer's discretion.
> I've done some grepping to verify that this change is consistent.
Oh, thank you. I checked the other new terms, but didn't check may and
optional.
> So how about adding "In such cases, ..." right before "... these words
> describe decisions ...", to clarify that your new text is not exhaustive
> regarding usage of 'may' and 'optional' in Policy?
I agree, but let's also fix existing incorrect wording. I reviewed every
instance of may and optional in Policy, and I think this larger diff will
make wording (mostly) consistent. I've tried not to change the sense of
any of these Policy statements (even though a few are questionable and
should probably be revisited).
Most of the problems fixed here were also inconsistent with the previous
wording and definition of may or optional. I didn't catch any mentions
that were using may in the wishlist bug sense, and only one instance of
optional used that way.
diff --git a/policy/ch-archive.rst b/policy/ch-archive.rst
index b8ba081..e37ebee 100644
--- a/policy/ch-archive.rst
+++ b/policy/ch-archive.rst
@@ -329,8 +329,8 @@ management tools.
the user doesn't select anything else. It doesn't include many large
applications.
- No two packages that both have a priority of ``standard`` or higher
- may conflict with each other.
+ Two packages that both have a priority of ``standard`` or higher must
+ not conflict with each other.
``optional``
This is the default priority for the majority of the archive. Unless
diff --git a/policy/ch-binary.rst b/policy/ch-binary.rst
index 74a1690..f1e518e 100644
--- a/policy/ch-binary.rst
+++ b/policy/ch-binary.rst
@@ -362,8 +362,8 @@ adding or removing diversions, package maintainer scripts must provide
the ``--package`` flag to ``dpkg-divert`` and must not use ``--local``.
All packages which supply an instance of a common command name (or, in
-general, filename) should generally use ``update-alternatives``, so that
-they may be installed together. If ``update-alternatives`` is not used,
+general, filename) should generally use ``update-alternatives`` so that
+they can be installed together. If ``update-alternatives`` is not used,
then each package must use ``Conflicts`` to ensure that other packages
are removed. (In this case, it may be appropriate to specify a conflict
against earlier versions of something that previously did not use
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 60edc82..1dd702c 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -72,7 +72,7 @@ Whitespace must not appear inside names (of packages, architectures,
files or anything else) or version numbers, or between the characters of
multi-character version relationships.
-The presence and purpose of a field, and the syntax of its value may
+The presence and purpose of a field, and the syntax of its value, may
differ between types of control files.
Field names are not case-sensitive, but it is usual to capitalize the
@@ -553,7 +553,7 @@ The three components here are:
``epoch``
This is a single (generally small) unsigned integer. It may be
omitted, in which case zero is assumed. If it is omitted then the
- ``upstream_version`` may not contain any colons.
+ ``upstream_version`` must not contain any colons.
Epochs can help when the upstream version numbering scheme
changes, but they must be used with care. You should not change
@@ -572,19 +572,19 @@ The three components here are:
respect to the ``upstream_version`` is described below. The
``upstream_version`` portion of the version number is mandatory.
- The ``upstream_version`` may contain only alphanumerics [#]_ and
+ The ``upstream_version`` must contain only alphanumerics [#]_ and
the characters ``.`` ``+`` ``-`` ``~`` (full stop, plus, hyphen,
tilde) and should start with a digit. If there is no
``debian_revision`` then hyphens are not allowed.
``debian_revision``
This part of the version number specifies the version of the Debian
- package based on the upstream version. It may contain only
+ package based on the upstream version. It must contain only
alphanumerics and the characters ``+`` ``.`` ``~`` (plus, full stop,
tilde) and is compared in the same way as the ``upstream_version`` is.
It is optional; if it isn't present then the ``upstream_version``
- may not contain a hyphen. This format represents the case where a
+ must not contain a hyphen. This format represents the case where a
piece of software was written specifically to be a Debian package,
where the Debian package source must always be identical to the
pristine source and therefore no revision indication is required.
@@ -1066,7 +1066,7 @@ The field can consist of exactly one of the following three items:
- A space separated list of keywords described below. These keywords
must always contain a forward slash, which sets them apart from the
other possible values of ``Rules-Requires-Root``. When this list
- is provided, the builder must provide a `gain root command` (as
+ is provided, the builder must provide a "gain root command" (as
defined in :ref:`debian/rules and Rules-Requires-Root
<s-debianrules-gainrootapi>`) *or* pretend that the value was set
to ``binary-targets``, and both the builder and the package's
@@ -1128,10 +1128,9 @@ In addition to the keywords defined in the next section, each tool or
package may define keywords within a namespace named after that tool
or package. The package or tool is considered to own that namespace.
-A tool may use the `gain root command` to do something under
-(fake)root if and only if the tool defines an appropriate keyword in
-its namespace, and the package lists that keyword in
-``Rules-Requires-Root``.
+A tool is permitted to use the "gain root command" to do something under
+(fake)root if and only if the tool defines an appropriate keyword in its
+namespace, and the package lists that keyword in ``Rules-Requires-Root``.
All tools must ignore keywords under namespaces they do not know or
own. A tool may emit a warning, or abort with an error, if it finds
diff --git a/policy/ch-customized-programs.rst b/policy/ch-customized-programs.rst
index dfe6ce4..18e318b 100644
--- a/policy/ch-customized-programs.rst
+++ b/policy/ch-customized-programs.rst
@@ -139,11 +139,8 @@ web servers and web applications in the Debian system.
3. Access to images
- It is recommended that images for a package be stored in
- ``/usr/share/images/package`` and may be referred to through an alias
- ``/images/`` as
-
- ::
+ Images for a package should be stored in ``/usr/share/images/package``
+ and referred to through an alias ``/images/`` as::
http://localhost/images/package/filename
diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst
index e990f34..a2e9be3 100644
--- a/policy/ch-docs.rst
+++ b/policy/ch-docs.rst
@@ -141,7 +141,7 @@ separately, as package-doc for example, it may be installed under either
that path or into the documentation directory for the separate
documentation package (``/usr/share/doc/package-doc`` in this example).
However, installing the documentation into the documentation directory
-of the main package is preferred since it is independent of the
+of the main package is encouraged since it is independent of the
packaging method and will be easier for users to find.
Any separate package providing documentation must still install standard
@@ -159,7 +159,8 @@ documentation should be installed elsewhere, such as under
``/usr/share/doc/package`` may be a symbolic link to another directory
in ``/usr/share/doc`` only if the two packages both come from the same
-source and the first package Depends on the second. [#]_
+source and the first package Depends on the second. Otherwise,
+``/usr/share/doc/package`` must not be a symbolic link. [#]_
.. _s12.4:
@@ -203,7 +204,8 @@ in the source package.
``/usr/share/doc/package`` may be a symbolic link to another directory
in ``/usr/share/doc`` only if the two packages both come from the same
-source and the first package Depends on the second. These rules are
+source and the first package Depends on the second. Otherwise,
+``/usr/share/doc/package`` must not be a symbolic link. These rules are
important because ``copyright`` files must be extractable by mechanical
means.
@@ -229,9 +231,8 @@ Machine-readable copyright information
A specification for a standard, machine-readable format for
``debian/copyright`` files is maintained as part of the debian-policy
-package. This document may be found in the ``copyright-format`` files in
-the debian-policy package. It is also available from the Debian web
-mirrors at
+package. This document is in the ``copyright-format`` files in the
+debian-policy package. It is also available from the Debian web mirrors at
https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/.
Use of this format is optional.
diff --git a/policy/ch-files.rst b/policy/ch-files.rst
index 48410be..1577295 100644
--- a/policy/ch-files.rst
+++ b/policy/ch-files.rst
@@ -18,7 +18,7 @@ which program will have to be renamed. If a consensus cannot be reached,
*both* programs must be renamed.
To support merged-\ ``/usr`` systems, packages must not install files in
-both ``/path`` and ``/usr/path``. For example, a package may not install
+both ``/path`` and ``/usr/path``. For example, a package must not install
both ``/bin/example`` and ``/usr/bin/example``.
If a file is moved between ``/path`` and ``/usr/path`` in revisions of a
@@ -409,8 +409,8 @@ default version will be part of the package distribution, and must not
be modified by the maintainer scripts during installation (or at any
other time).
-In order to ensure that local changes are preserved correctly, no
-package may contain or make hard links to conffiles. [#]_
+In order to ensure that local changes are preserved correctly, packages
+must not contain or make hard links to conffiles. [#]_
The other way to do it is via the maintainer scripts. In this case, the
configuration file must not be listed as a ``conffile`` and must not be
@@ -582,8 +582,8 @@ Permissions and owners
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 should try to be as
-consistent as possible with the rest of the system. You should probably
-also discuss it on ``debian-devel`` first.
+consistent as possible with the rest of the system. You are also
+encouraged to discuss it on ``debian-devel`` first.
Files should be owned by ``root:root``, and made writable only by the
owner and universally readable (and executable, if appropriate), that is
diff --git a/policy/ch-maintainerscripts.rst b/policy/ch-maintainerscripts.rst
index 707f2d4..709aabf 100644
--- a/policy/ch-maintainerscripts.rst
+++ b/policy/ch-maintainerscripts.rst
@@ -184,7 +184,7 @@ The ``postrm`` script may be called in the following ways:
removed or replaced. The package whose ``postrm`` is being called
may have previously been deconfigured and only be "Unpacked", at
which point subsequent package changes do not consider its
- dependencies. Therefore, all ``postrm`` actions may only rely on
+ dependencies. Therefore, all ``postrm`` actions must only rely on
essential packages and must gracefully skip any actions that require
the package's dependencies if those dependencies are unavailable.
[#]_
diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index b34c64c..eca855d 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -42,14 +42,14 @@ Debian Policy. The following exceptions to the FHS apply:
and ``/usr/lib{,32}`` is amended, permitting files to instead be
installed to ``/lib/triplet`` and ``/usr/lib/triplet``, where
``triplet`` is the value returned by ``dpkg-architecture -qDEB_HOST_MULTIARCH`` for the architecture of the
- package. Packages may *not* install files to any triplet path other
+ package. Packages must not install files to any triplet path other
than the one matching the architecture of that package; for
instance, an ``Architecture: amd64`` package containing 32-bit x86
- libraries may not install these libraries to
+ libraries must not install these libraries to
``/usr/lib/i386-linux-gnu``. [#]_
- No package for a 64 bit architecture may install files in
- ``/usr/lib64/`` or in a subdirectory of it.
+ Packages must not install files in ``/usr/lib64`` or in a subdirectory
+ of it.
The requirement for C and C++ headers files to be accessible through
the search path ``/usr/include/`` is amended, permitting files to be
@@ -481,7 +481,7 @@ Instead, they should be placed in a file in ``/etc/default``, which
typically will have the same base name as the ``init.d`` script. This
extra file should be sourced by the script when the script runs. It must
contain only variable settings and comments in POSIX.1-2017 ``sh`` format. It
-may either be a ``conffile`` or a configuration file maintained by the
+must either be a ``conffile`` or a configuration file maintained by the
package maintainer scripts. See :ref:`s-config-files` for
more details.
@@ -529,8 +529,8 @@ archive or manually create or remove the symbolic links in maintainer
scripts; you must use the ``update-rc.d`` program instead. (The former
will fail if an alternative method of maintaining runlevel information
is being used.) You must not include the ``/etc/rcn.d`` directories
-themselves in the archive either. (Only the ``sysvinit`` package may do
-so.)
+themselves in the archive either. (Only the ``init-system-helpers``
+package may do so.)
To get the default behavior for your package, put in your ``postinst``
script::
@@ -562,10 +562,10 @@ package's init script would not start the service until the local
system administrator changed this to ``DISABLED=no``, or similar. The
problem with this approach was that it hides from the init system
whether or not the daemon should actually be started, which leads to
-inconsistent and confusing behavior: ``service <package> start`` may
+inconsistent and confusing behavior: ``service <package> start`` could
return success but not start the service; services with a dependency
on this service will be started even though the service isn't running;
-and init system status commands may incorrectly claim that the service
+and init system status commands could incorrectly claim that the service
was started.
Note that if your package changes runlevels or priority, you may have to
diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
index 140fdf1..eb6c6d6 100644
--- a/policy/ch-relationships.rst
+++ b/policy/ch-relationships.rst
@@ -143,7 +143,7 @@ Binary Dependencies - ``Depends``, ``Recommends``, ``Suggests``, ``Enhances``, `
----------------------------------------------------------------------------------------------
Packages can declare in their control file that they have certain
-relationships to other packages - for example, that they may not be
+relationships to other packages - for example, that they cannot be
installed at the same time as certain other packages, and/or that they
depend on the presence of others.
@@ -379,7 +379,7 @@ problem. ``Breaks`` should be used
- when two packages provide the same file and will continue to do so,
- in conjunction with ``Provides`` when only one package providing a
- given virtual facility may be unpacked at a time (see
+ given virtual facility can be unpacked at a time (see
:ref:`s-virtual`),
- in other cases where one must prevent simultaneous installation of
diff --git a/policy/ch-scope.rst b/policy/ch-scope.rst
index 2404e84..0de9aab 100644
--- a/policy/ch-scope.rst
+++ b/policy/ch-scope.rst
@@ -31,21 +31,41 @@ part of Debian policy itself.
The appendices to this manual are not necessarily normative, either.
Please see :doc:`ap-pkg-scope` for more information.
-In the normative part of this manual, the words *must*, *should* and
-*may*, and the adjectives *required*, *recommended* and *optional*, are
-used to distinguish the significance of the various guidelines in this
-policy document. Packages that do not conform to the guidelines denoted
-by *must* (or *required*) will generally not be considered acceptable
-for the Debian distribution. Non-conformance with guidelines denoted by
-*should* (or *recommended*) will generally be considered a bug, but will
-not necessarily render a package unsuitable for distribution. Guidelines
-denoted by *may* (or *optional*) are truly optional and adherence is
-left to the maintainer's discretion.
-
-These classifications are roughly equivalent to the bug severities
-*serious* (for *must* or *required* directive violations), *minor*,
-*normal* or *important* (for *should* or *recommended* directive
-violations) and *wishlist* (for *optional* items). [#]_
+In the normative part of this manual, the following terms are used to
+describe the importance of each statement: [#]_
+
+* The terms *must* and *must not*, and the adjectives *required* and
+ *prohibited*, denote strong requirements. Packages that do not conform
+ to these requirements will generally not be considered acceptable for
+ the Debian distribution. These statements correspond to the *critical*,
+ *grave*, and *serious* bug severities (normally serious). They are
+ collectively called *Policy requirements*.
+
+* The terms *should* and *should not*, and the adjective *recommended*,
+ denote best practices. Non-conformance with these guidelines will
+ generally be considered a bug, but will not necessarily render a package
+ unsuitable for distribution. These statements correspond to bug
+ severities of *important*, *normal*, and *minor*. They are collectively
+ called *Policy recommendations*.
+
+* The adjectives *encouraged* and *discouraged* denote places where Policy
+ offers advice to maintainers, but maintainers are free to follow or not
+ follow that advice. Non-conformance with this advice is normally not
+ considered a bug; if a bug seems worthwhile, normally it would have a
+ severity of *wishlist*. These statements are collectively calld *Policy
+ advice*.
+
+* The term *may* and the adjective *optional* are sometimes used to
+ clarify cases where it may otherwise appear that Policy is specifying a
+ requirement or recommendation. In those cases, these words describe
+ decisions that are truly optional and at the maintainer's discretion.
+
+The Release Team may, at their discretion, downgrade a Policy requirement
+to a Policy recommendation for a given release of the Debian distribution.
+This may be done for only a specific package or for the archive as a
+whole. This provision is intended to provide flexibility to balance the
+quality standards of the distribution against the release schedule and the
+importance of making a stable release.
Much of the information presented in this manual will be useful even
when building a package which is to be distributed in some other way or
diff --git a/policy/ch-sharedlibs.rst b/policy/ch-sharedlibs.rst
index 80ef627..34fbbd6 100644
--- a/policy/ch-sharedlibs.rst
+++ b/policy/ch-sharedlibs.rst
@@ -89,7 +89,7 @@ be unnecessarily difficult because of file conflicts with the old
version of the package. When in doubt, always split shared library
packages so that each binary package installs a single shared library.
-Every time the shared library ABI changes in a way that may break
+Every time the shared library ABI changes in a way that could break
binaries linked against older versions of the shared library, the
``SONAME`` of the library and the corresponding name for the binary
package containing the runtime shared library should change. Normally,
@@ -322,7 +322,7 @@ shared library with only a ``shlibs`` file, the generated dependency
will require a version of the shared library equal to or newer than the
version of the last ABI change. This generates unnecessarily restrictive
dependencies compared to ``symbols`` files if none of the symbols used
-by the package have changed. This, in turn, may make upgrades needlessly
+by the package have changed. This, in turn, could make upgrades needlessly
complex and unnecessarily restrict use of the package on systems with
older versions of the shared libraries.
@@ -470,9 +470,9 @@ dependency version (for ``shlibs``) files. But special care should be
taken to update dependency versions when the behavior of a public symbol
changes. This is easy to neglect, since there is no automated method of
determining such changes, but failing to update versions in this case
-may result in binary packages with too-weak dependencies that will fail
+could result in binary packages with too-weak dependencies that will fail
at runtime, possibly in ways that can cause security vulnerabilities. If
-the package maintainer believes that a symbol behavior change may have
+the package maintainer believes that a symbol behavior change could have
occurred but isn't sure, it's safer to update the version rather than
leave it unmodified. This may result in unnecessarily strict
dependencies, but it ensures that packages whose dependencies are
diff --git a/policy/ch-source.rst b/policy/ch-source.rst
index 93beb4a..9c92bf7 100644
--- a/policy/ch-source.rst
+++ b/policy/ch-source.rst
@@ -251,7 +251,7 @@ source files in a package, as far as is reasonably possible. [#]_
Restrictions on objects in source packages
------------------------------------------
-The source package may not contain any hard links, [#]_ device special
+The source package must not contain any hard links, [#]_ device special
files, sockets or setuid or setgid files.. [#]_
.. _s-debianrules:
@@ -307,7 +307,7 @@ commands it invokes options that cause them to produce verbose output.
For example, the build target should pass ``--disable-silent-rules``
to any configure scripts. See also :ref:`s-binaries`.
-For packages in the main archive, no required targets may attempt
+For packages in the main archive, required targets must not attempt
network access, except, via the loopback interface, to services on the
build host that have been started by the build.
@@ -659,14 +659,15 @@ including the format of ``debian/substvars``.
.. _s-debianwatch:
-Optional upstream source location: ``debian/watch``
----------------------------------------------------
+Upstream source location: ``debian/watch``
+------------------------------------------
-This is an optional, recommended configuration file for the ``uscan``
-utility which defines how to automatically scan ftp or http sites for
-newly available updates of the package. This is also used by some Debian
-QA tools to help with quality control and maintenance of the
-distribution as a whole.
+This is a configuration file for the ``uscan`` utility which defines how
+to automatically scan ftp or http sites for newly available updates of the
+package. This is also used by some Debian QA tools to help with quality
+control and maintenance of the distribution as a whole. If the upstream
+source of the package is available via a mechaism that ``uscan``
+understands, including this configuration file is recommended.
If the upstream maintainer of the software provides OpenPGP signatures
for new releases, including the information required for ``uscan`` to
@@ -797,14 +798,13 @@ the upstream tarball. In order to satisfy the DFSG for packages in
2. include a copy of the sources in the ``debian/missing-sources``
directory.
-There is an optional convention to organise the contents of
-``debian/missing-sources`` in the following way. For a sourceless
-file ``foo`` in the subdirectory ``bar`` of the upstream tarball,
-where the source of ``foo`` has extension ``baz``, the source is to be
-located at ``debian/missing-sources/bar/foo.baz``. For example,
-according to this convention, the C source code of an executable
-``checksum/util`` is to be located at
-``debian/missing-sources/checksum/util.c``.
+Package maintainers are encouraged to use the following convention to
+organize the contents of ``debian/missing-sources``: for a sourceless file
+``foo`` in the subdirectory ``bar`` of the upstream tarball, where the
+source of ``foo`` has extension ``baz``, the source is to be located at
+``debian/missing-sources/bar/foo.baz``. For example, according to this
+convention, the C source code of an executable ``checksum/util`` would be
+located at ``debian/missing-sources/checksum/util.c``.
Vendor-specific patch series
----------------------------
--
Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>
Reply to: