Bug#944920: Revise terminology used to specify requirements

[Russ Allbery <rra@debian.org>]

Sean Whitton <spwhitton@spwhitton.name> 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 (rra@debian.org)              <https://www.eyrie.org/~eagle/>