Bug#944920: Revise terminology used to specify requirements
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
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 isn
Bug#944920: Revise terminology used to specify requirements
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
