Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

control: tag -1 + pending

Hello,

On Thu 01 Apr 2021 at 10:44AM -07, Russ Allbery wrote:

> Russ Allbery  writes:
>
>> 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.
>
> It's been over a year since the last activity on this bug so although
> there were enough seconds for a revised form of this patch, I'm reposting
> it to remind people where the discussion was and as a quick double-check
> that I didn't mess up the rebase.

Thank you for confirming you are okay with changing d/missing-sources
back and for rebasing the series -- now merged to 'next'.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Sam Hartman]

> "Russ" == Russ Allbery  writes:

Russ> Russ Allbery  writes:
>> 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.

Russ> It's been over a year since the last activity on this bug so
Russ> although there were enough seconds for a revised form of this
Russ> patch, I'm reposting it to remind people where the discussion
Russ> was and as a quick double-check that I didn't mess up the
Russ> rebase.

Hi.
I reconfirm my second after reviewing the patch.


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

Russ Allbery  writes:

> 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.

It's been over a year since the last activity on this bug so although
there were enough seconds for a revised form of this patch, I'm reposting
it to remind people where the discussion was and as a quick double-check
that I didn't mess up the rebase.

This includes relaxing the debian/missing-sources wording back to optional
again, although I kept some rewording of that paragraph to hopefully make
it a bit clearer.

Proposed debian/changelog entry:

  * Policy: Add new encouraged keyword, make keywords consistent
Wording: Russ Allbery 
Seconded: Sam Hartman 
Seconded: Sean Whitton 
Closes: #944920
  * Clarify that no package may install files in /usr/lib64.  The previous
wording implied this restriction only applied to 64-bit packages.
  * Reserve the /etc/rcn.d directories for the init-system-helpers package
rather than the sysvinit package, reflecting a change already made in
the archive.

Attached is a regular unified diff since I think that's marginally easier
to read (although I'm very used to unified diffs).  For folks who want a
word diff instead, clone https://salsa.debian.org/dbnpolicy/policy.git and
run git diff --word-diff next..bug944920-rra

-- 
Russ Allbery (r...@debian.org)  

diff --git a/debian/changelog b/debian/changelog
index fe13e5a..b4d81f1 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,5 +1,6 @@
 debian-policy (4.5.2.0) UNRELEASED; urgency=medium
 
+  [ Sean Whitton ]
   * Policy: Allow manpages to be included in the dependencies of packages
 Wording: Helmut Grohne 
 Seconded: Russ Allbery 
@@ -7,6 +8,18 @@ debian-policy (4.5.2.0) UNRELEASED; urgency=medium
 Seconded: Sean Whitton 
 Closes: #983657
 
+  [ Russ Allbery ]
+  * Policy: Add new encouraged keyword, make keywords consistent
+Wording: Russ Allbery 
+Seconded: Sam Hartman 
+Seconded: Sean Whitton 
+Closes: #944920
+  * Clarify that no package may install files in /usr/lib64.  The previous
+wording implied this restriction only applied to 64-bit packages.
+  * Reserve the /etc/rcn.d directories for the init-system-helpers package
+rather than the sysvinit package, reflecting a change already made in
+the archive.
+
  -- Sean Whitton   Sun, 28 Feb 2021 14:25:28 -0700
 
 debian-policy (4.5.1.0) unstable; urgency=medium
diff --git a/policy/ch-archive.rst b/policy/ch-archive.rst
index 5fbc0a3..ab04261 100644
--- a/policy/ch-archive.rst
+++ b/policy/ch-archive.rst
@@ -348,8 +348,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 784bca3..937d0d9 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 a21a510..fdb1b51 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
@@ -571,19 +571,19 @@ The three components here are:
 respect to the ``upstream_version`` is described below. The
 

Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

Hello,

On Sat 29 Feb 2020 at 09:38PM -08, Russ Allbery wrote:

> Sean Whitton  writes:
>
>> One issue with using uppercased words is that people might think the
>> words have the same meaning as they do in RFCs, which they don't.
>
>> Your idea of marking keywords in bold wouldn't have this problem, and
>> maybe it would actually make it /easier/ to write patches because you
>> can see more clearly which of your words mean what.
>
> It does have the drawback of being either less obvious or a bit noisy in
> the text output format, though, which I suspect is reasonably heavily
> used.

Oh, excellent point (indeed, it's the main way I read Policy...).

> I'm not sure our definitions are that far off from the RFC terms.  We're
> not defining a protocol, so it's inherently a little different, but there
> are some clear equivalents.  And it would avoid reinventing a new
> typographic convention.
>
> A long time ago, Manoj proposed a deeper, more comprehensive fix: stop
> writing Policy as English prose and instead explicitly state normative
> requirements in some sort of numbered, clear fashion, and then add a prose
> informative explanation if warranted.  But I'm a bit dubious of that.  Not
> only would it be a ton of work, but the more formal phrasing will require
> repeating ourself a lot more.

Yes, it is not clear it would be worth it.

>> Thinking more, I believe that the issue you're raising here is separate
>> from what Russ is trying to achieve in this bug.  The problem you're
>> identifying here already exists in Policy, before Russ's change is
>> applied.  So maybe we should discuss it separately.
>
> Yes, I'm behind but that was the thing I wanted to say: I'd like to merge
> this change (I haven't looked at more recent reviews, since I've been
> distracted with work, so I don't know off-hand if it's ready for merging
> otherwise) and then tackle this issue separately.  But I do think it's
> time to tackle it.

I believe that there are enough seconds (from Sam and I) for your most
recent patch, minus the debian/missing-sources change.  If you're okay
with dropping that, at least for now, then let's get this committed.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

Sean Whitton  writes:

> One issue with using uppercased words is that people might think the
> words have the same meaning as they do in RFCs, which they don't.

> Your idea of marking keywords in bold wouldn't have this problem, and
> maybe it would actually make it /easier/ to write patches because you
> can see more clearly which of your words mean what.

It does have the drawback of being either less obvious or a bit noisy in
the text output format, though, which I suspect is reasonably heavily
used.

I'm not sure our definitions are that far off from the RFC terms.  We're
not defining a protocol, so it's inherently a little different, but there
are some clear equivalents.  And it would avoid reinventing a new
typographic convention.

A long time ago, Manoj proposed a deeper, more comprehensive fix: stop
writing Policy as English prose and instead explicitly state normative
requirements in some sort of numbered, clear fashion, and then add a prose
informative explanation if warranted.  But I'm a bit dubious of that.  Not
only would it be a ton of work, but the more formal phrasing will require
repeating ourself a lot more.

Personally, I think I'm leaning mildly towards the all-caps keywords
because of familiarity and compatibility with a pure text format, although
I could be convinced otherwise.

I do think making this change is a good idea.

> Thinking more, I believe that the issue you're raising here is separate
> from what Russ is trying to achieve in this bug.  The problem you're
> identifying here already exists in Policy, before Russ's change is
> applied.  So maybe we should discuss it separately.

Yes, I'm behind but that was the thing I wanted to say: I'd like to merge
this change (I haven't looked at more recent reviews, since I've been
distracted with work, so I don't know off-hand if it's ready for merging
otherwise) and then tackle this issue separately.  But I do think it's
time to tackle it.

>> BTW I guess the instances of «might» and «shall» need to be converted,
>> or added to the keyword list? What about «may not», or «can», «can't»,
>> «cannot» and «could»? And I'm probably missing other words. :)

> I don't think we need to convert words that don't explicitly appear in
> the keywords list -- "may not" would inherit its meaning from "may"
> being a keyword, wouldn't it?

I think that if the word doesn't appear in the keyword list, it shouldn't
have any normative meaning.  I have intentionally used the words can and
cannot in Policy text precisely because they don't have normative meaning
and don't state Policy requirements.  For example, in:

If punctuation is desired between the date components, remember that
hyphen (``-``) cannot be used in native package versions.

the "cannot" is not a normative Policy requirement, just a description of
a logical consequence of a definition stated earlier.

-- 
Russ Allbery (r...@debian.org)  

Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

Hello Guillem,

On Thu 30 Jan 2020 at 01:16AM +01, Guillem Jover wrote:

> Some of the words chosen to convey normative meaning are glue words
> used to build pretty mundane sentences, so having them appear around
> while they might not convey normative meaning seems rather confusing,
> and is a mental overhead when reading or drafting new text. Probably
> more for non-native speakers.

Thank you, I hadn't thought of it in terms of increasing the effort
required to draft new text, which holds even if we fix all existing
instances.

> For example in ch-scope.rst in the entry describing the *may* keyword
> the following sentence uses also «may». :) The ch-archive.rst contains
> several «may» instances that do not feel like the normative *may*, at
> least the ones in the DFSG?
>
> Perhaps instead of the potentially ugly uppercased keywords, marking
> them as *keyword* like in the definition of the terms would go a long
> way?

One issue with using uppercased words is that people might think the
words have the same meaning as they do in RFCs, which they don't.

Your idea of marking keywords in bold wouldn't have this problem, and
maybe it would actually make it /easier/ to write patches because you
can see more clearly which of your words mean what.

Thinking more, I believe that the issue you're raising here is separate
from what Russ is trying to achieve in this bug.  The problem you're
identifying here already exists in Policy, before Russ's change is
applied.  So maybe we should discuss it separately.

> BTW I guess the instances of «might» and «shall» need to be converted,
> or added to the keyword list? What about «may not», or «can», «can't»,
> «cannot» and «could»? And I'm probably missing other words. :)

I don't think we need to convert words that don't explicitly appear in
the keywords list -- "may not" would inherit its meaning from "may"
being a keyword, wouldn't it?

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Guillem Jover]

On Wed, 2020-01-29 at 14:42:08 -0700, Sean Whitton wrote:
> On Sun 26 Jan 2020 at 03:48AM +01, Guillem Jover wrote:
> > I think one of the nice things about RFC2119 is that it uses uppercase
> > versions for the normative keywords, so that these are very clearly
> > distinguished both when writing and readin, from sentences that may
> > use some of the common words but that do not carry any normative
> > meaning. Was there any consideration in using uppercased keywords?
> 
> Well, Russ has now gone through and eliminated non-normative use of the
> keywords, so I think the question is moot.

Ok, let me try again, because I'm not sure I expressed my concern
clearly.

Some of the words chosen to convey normative meaning are glue words
used to build pretty mundane sentences, so having them appear around
while they might not convey normative meaning seems rather confusing,
and is a mental overhead when reading or drafting new text. Probably
more for non-native speakers.

For example in ch-scope.rst in the entry describing the *may* keyword
the following sentence uses also «may». :) The ch-archive.rst contains
several «may» instances that do not feel like the normative *may*, at
least the ones in the DFSG?

Perhaps instead of the potentially ugly uppercased keywords, marking
them as *keyword* like in the definition of the terms would go a long
way?


BTW I guess the instances of «might» and «shall» need to be converted,
or added to the keyword list? What about «may not», or «can», «can't»,
«cannot» and «could»? And I'm probably missing other words. :)

Thanks,
Guillem

Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

Hello,

On Sun 26 Jan 2020 at 03:48AM +01, Guillem Jover wrote:

> I think one of the nice things about RFC2119 is that it uses uppercase
> versions for the normative keywords, so that these are very clearly
> distinguished both when writing and readin, from sentences that may
> use some of the common words but that do not carry any normative
> meaning. Was there any consideration in using uppercased keywords?

Well, Russ has now gone through and eliminated non-normative use of the
keywords, so I think the question is moot.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Guillem Jover]

On Fri, 2020-01-03 at 20:43:14 -0800, Russ Allbery wrote:
> Russ Allbery  writes:
> > 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).
> 
> Here is an updated version of this patch, including the upgrading
> checklist entry. […]

> Most of this diff is changing normative "may not" phrasings to "must not"
> or some other equivalent, and changing other uses of "may" to "could" or
> other wordings.

I think one of the nice things about RFC2119 is that it uses uppercase
versions for the normative keywords, so that these are very clearly
distinguished both when writing and readin, from sentences that may
use some of the common words but that do not carry any normative
meaning. Was there any consideration in using uppercased keywords?

(I'm asking this irrespective of the actual words being used.)

Thanks,
Guillem

Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

Hello,

On Fri 03 Jan 2020 at 08:43PM -08, Russ Allbery wrote:

> Russ Allbery  writes:
>
>> 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).
>
> Here is an updated version of this patch, including the upgrading
> checklist entry.  I tried using a word diff, but I think the line diff is
> more readable and easier to understand.  I at least found it easier to
> understand the wording changes in that format (maybe this is just my long
> familiarity with reviewing line diffs).
>
> I think this is ready for seconds, assuming that one agrees with the three
> places that I made semantic changes (/usr/lib64, init-system-helpers, and
> deciding on encouraged for debian/missing-sources).
>
> Most of this diff is changing normative "may not" phrasings to "must not"
> or some other equivalent, and changing other uses of "may" to "could" or
> other wordings.
>
> This retains the statement about the release team's role in changing the
> severity of Policy requirements, since I think that was the outcome of the
> side conversation.  I'll work on an appendix accumulating all Policy
> requirements in a separate patch.
>
> 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 0d7a3e9..8d43130 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 

Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

Hello,

On Fri 03 Jan 2020 at 08:27PM -08, Russ Allbery wrote:

> Sean Whitton  writes:
>> On Sun 17 Nov 2019 at 05:48PM -08, Russ Allbery wrote:
>
>>>  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.)
>
>> Likewise, isn't this a semantic change?
>
> This is, but I think it's a bookkeeping change.  Those directories are in
> init-system-helpers rather than sysvinit in the archive right now, and
> that clearly shouldn't be a policy violation.
>
> Ideally it should probably be in a separate commit, but in looking at this
> again I also want to change "may do so" to "is permitted to do so."  I can
> break it out if needed, but I'd rather commit it as part of this set of
> changes (and will document it separately in debian/changelog; I don't
> think it warrants adding to upgrading-checklist since it only affects one
> set of maintainers who already know).

Cool, let's just fold it in.

>>> @@ -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``.
>
>> I don't think this should be strengthened to something Policy
>> encourages, or if it should, we should discuss it in a separate bug.  So
>> I'd like to suggest using none of the magic words in this paragraph,
>> just starting it with "There is a convention to organise ..."
>
> I think this is a change where the distinction between optional and
> encouraged is valuable and this would have been written as encouraged if
> we had that concept.  There's not much point in a convention unless we
> advise maintainers to follow it, and that seems like an appropriate use of
> Policy advice.
>
> Does that make sense?  I can revise it if you don't like it after that
> explanation, but it feels perfect for "encourage."

I see where you are coming from, but from my memories of handling the
bug where we added this text, it actually was a matter of documenting a
convention without advising maintainers to follow it.

My thought at the time was that we should document the existing
convention only in order to avoid ending up with more than one
convention in use in the archive -- to avoid, say, several different
packaging teams writing down distinct conventions in team docs.

However, I didn't think that we had a project consensus that (a) there
was a need for a standard way to organise d/missing-sources, or that (b)
maintainers should be spending time organising d/missing-sources, rather
than just putting the source files somewhere in there and moving on.

The thought, then, was to document the convention to avoid ending up
with more than one, and then just wait and see whether the project came
to a consensus that it's actually worthwhile to carefully organise
d/missing-sources.

If we do raise this to the level of Policy advice then we're adding to
maintainer workloads, and that's something we should always be careful
about doing, which is why I would prefer to discuss that change in a
separate bug.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

Sam Hartman  writes:

> One question:

> +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.

> I wonder if that should be can (or is permitted) rather than may.

Good point.  I agree with your analysis and will change this in my draft
version to "The Release Team can".

-- 
Russ Allbery (r...@debian.org)  

Bug#944920: Revise terminology used to specify requirements

[Sam Hartman]

Russ, I've reviewed your new patch.

I haven't been participating in this discussion before, but I think it
is fair to say that I have significant experience with these sorts of
normative language discussions and Debian policy in general.

I agree with all your changes (with one question below).
My review was insufficient to catch changes you should hav made but did
not.

One question:

+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.

I wonder if that should be can (or is permitted) rather than may.
Saying it is optional implies that the policy is not making a
recommendation on whether they should make such changes.
I guess that's true, but either:

1) it's in scope for the policy to permit this.  In which case may is
too weak.

2) It's out of scope, in which you should not use normative language at
all.

Some will argue that it's inherently out of scope for you to make that
recommendation because of separation of concerns between the policy
editors and release team.
I think it would be inappropriate for the policy editors to update what
policy says about what the release team can do without sign-off from the
release team  (or change in the delegation text).  For example it would
clearly be inappropriate for the policy editors to change "is permitted"
to "must not" in the above without the release team agreeing.
But I think whether policy makes normative documentation in this space
should be decided based on what is best for the project rather than on
who all would have to approve such changes.

That said, can is simpler.

Regardless of may, can, or is permitted, I second your patch.


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

Sean Whitton  writes:

> Let's definitely reconsider those 'must' requirements in response to
> this work, but let's not commit ourselves to the idea that it's always a
> bug for the Release Team's conception of an RC bug, and Policy 'must'
> requirements, to disagree.

> The Release Team's conception of RC bugs, and the text of Policy, are
> generated and updated by different processes, for different purposes.  I
> think Debian benefits from that diversity of normative processes, and it
> would harm that to try too hard to keep the output of the two processes
> in perfect sync.

Yes, that's put better than I put it.  Thank you.  I was too focused on
the fact that I suspect we'll find some musts that are too aggressive, but
indeed, allowing these things to differ is part of why I'm proposing
explicit language to allow the Release Team to downgrade requirements to
recommendations.

-- 
Russ Allbery (r...@debian.org)  

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

Russ Allbery  writes:

> 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).

Here is an updated version of this patch, including the upgrading
checklist entry.  I tried using a word diff, but I think the line diff is
more readable and easier to understand.  I at least found it easier to
understand the wording changes in that format (maybe this is just my long
familiarity with reviewing line diffs).

I think this is ready for seconds, assuming that one agrees with the three
places that I made semantic changes (/usr/lib64, init-system-helpers, and
deciding on encouraged for debian/missing-sources).

Most of this diff is changing normative "may not" phrasings to "must not"
or some other equivalent, and changing other uses of "may" to "could" or
other wordings.

This retains the statement about the release team's role in changing the
severity of Policy requirements, since I think that was the outcome of the
side conversation.  I'll work on an appendix accumulating all Policy
requirements in a separate patch.

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 0d7a3e9..8d43130 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 

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

Sean Whitton  writes:
> On Sun 17 Nov 2019 at 05:48PM -08, Russ Allbery wrote:

>>  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.)

> Likewise, isn't this a semantic change?

This is, but I think it's a bookkeeping change.  Those directories are in
init-system-helpers rather than sysvinit in the archive right now, and
that clearly shouldn't be a policy violation.

Ideally it should probably be in a separate commit, but in looking at this
again I also want to change "may do so" to "is permitted to do so."  I can
break it out if needed, but I'd rather commit it as part of this set of
changes (and will document it separately in debian/changelog; I don't
think it warrants adding to upgrading-checklist since it only affects one
set of maintainers who already know).

>> @@ -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``.

> I don't think this should be strengthened to something Policy
> encourages, or if it should, we should discuss it in a separate bug.  So
> I'd like to suggest using none of the magic words in this paragraph,
> just starting it with "There is a convention to organise ..."

I think this is a change where the distinction between optional and
encouraged is valuable and this would have been written as encouraged if
we had that concept.  There's not much point in a convention unless we
advise maintainers to follow it, and that seems like an appropriate use of
Policy advice.

Does that make sense?  I can revise it if you don't like it after that
explanation, but it feels perfect for "encourage."

-- 
Russ Allbery (r...@debian.org)  

Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

Hello,

On Sun 29 Dec 2019 at 11:20am -08, Russ Allbery wrote:

> Paul Gevers  writes:
>> On 21-11-2019 13:59, Paul Gevers wrote:
>
>>> [Disclaimer: the words below are as a member of the release team, but
>>> not necessarily those of the team. We haven't discussed this yet.]
>
>> We have had a discussion, and there were no objections against my vision
>> below.
>
>>> I can envision that if Policy carries such a summary list, our policy
>>> would mention the version of Policy it was based on, to make sure that
>>> Policy doesn't suddenly change what we as the RT agreed on.
>
>> So, yes, we would welcome the Policy to maintain a summary list that we
>> could reference. We already acknowledge that there will be items in the
>> Policy text that we balance differently for RC-ness, so there will be
>> exceptions maintained by us.
>
> Thanks, Paul!  This is now on me to compose this list, and I'll let you
> know when that's done.  Once that's complete, we can do a reconciliation.
> I'm inclined to downgrade Policy musts that the release team does not
> consider likely to be release-critical in the future, for instance.

Let's definitely reconsider those 'must' requirements in response to
this work, but let's not commit ourselves to the idea that it's always a
bug for the Release Team's conception of an RC bug, and Policy 'must'
requirements, to disagree.

The Release Team's conception of RC bugs, and the text of Policy, are
generated and updated by different processes, for different purposes.  I
think Debian benefits from that diversity of normative processes, and it
would harm that to try too hard to keep the output of the two processes
in perfect sync.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

Paul Gevers  writes:
> On 21-11-2019 13:59, Paul Gevers wrote:

>> [Disclaimer: the words below are as a member of the release team, but
>> not necessarily those of the team. We haven't discussed this yet.]

> We have had a discussion, and there were no objections against my vision
> below.

>> I can envision that if Policy carries such a summary list, our policy
>> would mention the version of Policy it was based on, to make sure that
>> Policy doesn't suddenly change what we as the RT agreed on.

> So, yes, we would welcome the Policy to maintain a summary list that we
> could reference. We already acknowledge that there will be items in the
> Policy text that we balance differently for RC-ness, so there will be
> exceptions maintained by us.

Thanks, Paul!  This is now on me to compose this list, and I'll let you
know when that's done.  Once that's complete, we can do a reconciliation.
I'm inclined to downgrade Policy musts that the release team does not
consider likely to be release-critical in the future, for instance.

-- 
Russ Allbery (r...@debian.org)  

Bug#944920: Revise terminology used to specify requirements

[Paul Gevers]

Dear Policy Editors,

On 21-11-2019 13:59, Paul Gevers wrote:
> [Disclaimer: the words below are as a member of the release team, but
> not necessarily those of the team. We haven't discussed this yet.]

We have had a discussion, and there were no objections against my vision
below.

> I can envision that if Policy carries such a summary list, our policy
> would mention the version of Policy it was based on, to make sure that
> Policy doesn't suddenly change what we as the RT agreed on.

So, yes, we would welcome the Policy to maintain a summary list that we
could reference. We already acknowledge that there will be items in the
Policy text that we balance differently for RC-ness, so there will be
exceptions maintained by us.

Paul



signature.asc
Description: OpenPGP digital signature

Bug#944920: Revise terminology used to specify requirements

[Paul Gevers]

Dear Russ,

[Disclaimer: the words below are as a member of the release team, but
not necessarily those of the team. We haven't discussed this yet.]

On 17-11-2019 20:47, Russ Allbery wrote:
> Let me copy the release team.  How would you all prefer to handle the
> relationship between release-criticality and Policy requirements?  I don't
> think as a project it's ideal to maintain two separate lists of
> requirements, but Policy currently doesn't have a nice summary list like
> that.
> 
> One possible option would be for Policy to take over maintenance of a
> summary list of all Policy requirements, and then the release team can
> maintain only a list of exceptions for a given Debian release.  Do you
> think that might be an improvement?

I think this would be an improvement, yes. As you can see at the top of
our policy, the list hasn't seen real proper review for years, although
some months ago I went through our policy to add cross-references to
Policy where I could find them. Those without the links would probably
be the RT amendments. I would love to have a list with the other items
to *also* be able to spot which ones aren't on our list (but should).

I can envision that if Policy carries such a summary list, our policy
would mention the version of Policy it was based on, to make sure that
Policy doesn't suddenly change what we as the RT agreed on.

Paul



signature.asc
Description: OpenPGP digital signature

Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

Hello,

On Mon 18 Nov 2019 at 05:34PM -08, Russ Allbery wrote:

> Yeah, that was my thought process, but I did totally break my own rule.  I
> can break this out into a separate change if that makes more sense.  I was
> trying to reword the sentence to avoid using "no ... may" and trying to
> keep the 64-bit qualification seemed very awkward.
>
> /usr/lib64 is for 64-bit architecture support the Red Hat way (instead of
> the Debian multiarch approach), so no 32-bit package would ever
> legitimately install files there.

Let's go ahead and make the change as part of resolving this bug, but
let's also mention the semantic change in the upgrading checklist, just
in case there is some strange edge case we've missed.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

David Bremner  writes:
> Sean Whitton  writes:

>>> -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.
>>
>> This seems to be a semantic change, generalising the requirement to all
>> packages?

> Well, I think you're both right. A lawyerly reading of policy might say
> 32 bit packages can install in /usr/lib64, but wouldn't that just be
> nonsensical, and maybe contradict other wording about FHS conformance

Yeah, that was my thought process, but I did totally break my own rule.  I
can break this out into a separate change if that makes more sense.  I was
trying to reword the sentence to avoid using "no ... may" and trying to
keep the 64-bit qualification seemed very awkward.

/usr/lib64 is for 64-bit architecture support the Red Hat way (instead of
the Debian multiarch approach), so no 32-bit package would ever
legitimately install files there.

-- 
Russ Allbery (r...@debian.org)  

Bug#944920: Revise terminology used to specify requirements

[David Bremner]

Sean Whitton  writes:

>
>> -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.
>
> This seems to be a semantic change, generalising the requirement to all
> packages?

Well, I think you're both right. A lawyerly reading of policy might say
32 bit packages can install in /usr/lib64, but wouldn't that just be
nonsensical, and maybe contradict other wording about FHS conformance

Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

Hello,

On Sun 17 Nov 2019 at 05:48PM -08, Russ Allbery wrote:

> 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).

Cool!  I think in this case we should s/sometimes used/used/ in your new
description of the use of 'may' and 'optional', right?

Review of the big diff:

> -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.

This seems to be a semantic change, generalising the requirement to all
packages?

>  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.)

Likewise, isn't this a semantic change?

> @@ -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``.

I don't think this should be strengthened to something Policy
encourages, or if it should, we should discuss it in a separate bug.  So
I'd like to suggest using none of the magic words in this paragraph,
just starting it with "There is a convention to organise ..."

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

Sean Whitton  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 

Bug#944920: Revise terminology used to specify requirements

[Sean Whitton]

Hello Russ,

Thanks for this.

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.

In section 4.11 we have "This is an optional, recommended configuration
file ..." and in other places too it seems that 'optional' gets used to
mean, specifically, that a computer program is not going to shout at you
if something is not present.

Additionally, I think that 'may' gets used in a few other ways -- it
comes up very many times and I haven't checked all of them.

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?

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

Bastian Blank  writes:
> On Sun, Nov 17, 2019 at 10:10:11AM -0800, Russ Allbery wrote:

>> +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.

> I don't think this aligns to the current release team practice, which
> provides a canonical list of points that are considered policy
> requirements:[1]

> | The purpose of this document is to be a correct, complete and canonical
> | list of issues that merit a "serious" bug under the clause "a severe
> | violation of Debian policy".

It doesn't exactly, although it can if you squint, since effectively the
release team is downgrading all other Policy requirements to Policy
recommendations by not listing them there.

Let me copy the release team.  How would you all prefer to handle the
relationship between release-criticality and Policy requirements?  I don't
think as a project it's ideal to maintain two separate lists of
requirements, but Policy currently doesn't have a nice summary list like
that.

One possible option would be for Policy to take over maintenance of a
summary list of all Policy requirements, and then the release team can
maintain only a list of exceptions for a given Debian release.  Do you
think that might be an improvement?

-- 
Russ Allbery (r...@debian.org)  

Bug#944920: Revise terminology used to specify requirements

[Bastian Blank]

On Sun, Nov 17, 2019 at 10:10:11AM -0800, Russ Allbery wrote:
> +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.

I don't think this aligns to the current release team practice, which
provides a canonical list of points that are considered policy
requirements:[1]

| The purpose of this document is to be a correct, complete and canonical
| list of issues that merit a "serious" bug under the clause "a severe
| violation of Debian policy".

Bastian

[1]: https://release.debian.org/bullseye/rc_policy.txt
-- 
It would be illogical to assume that all conditions remain stable.
-- Spock, "The Enterprise Incident", stardate 5027.3

Bug#944920: Revise terminology used to specify requirements

[Holger Levsen]

On Sun, Nov 17, 2019 at 10:10:11AM -0800, Russ Allbery wrote:
> 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

wow, nice!

> 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.
 
seconded, thank you.


-- 
cheers,
Holger

---
   holger@(debian|reproducible-builds|layer-acht).org
   PGP fingerprint: B8BF 5413 7B09 D35C F026 FE9D 091A B856 069A AA1C


signature.asc
Description: PGP signature

Bug#944920: Revise terminology used to specify requirements

[Russ Allbery]

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  

-- no debconf information