Bug#944920: Revise terminology used to specify requirements
Package: debian-policy
Version: 4.4.1.1
Severity: normal
In attempting to revise recent GRs to use the same terminology as
Policy, I got frustrated again by the lack of precision of our current
language. This is an attempt to make a minor improvement. It doesn't
go all the way to using all-caps terms the way that RFC 2119 does; I
think that might be an improvement, but it was a larger change than I
wanted to tackle.
Changes:
* Add "prohibited" to the terms for requirements
* Add another tier (Policy advice) using encouraged and discouraged
* Stop confusing may and optional with wishlist bugs
* Add terms for the collective set of Policy requirements at each tier
* Explicitly state the long-standing policy that the release team determines
release-critical bugs
diff --git a/policy/ch-scope.rst b/policy/ch-scope.rst
index 2404e84..98983e9 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. 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
-- System Information:
Debian Release: bullseye/sid
APT prefers unstable
APT policy: (990, 'unstable'), (500, 'unstable-debug'), (1, 'experimental')
Architecture: amd64 (x86_64)
Kernel: Linux 5.2.0-3-amd64 (SMP w/8 CPU cores)
Kernel taint flags: TAINT_PROPRIETARY_MODULE, TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
debian-policy depends on no packages.
Versions of packages debian-policy recommends:
ii libjs-sphinxdoc 1.8.5-3
Versions of packages debian-policy suggests:
pn doc-base <none>
-- no debconf information
Reply to: