Discussion:
Bug#944325: please fix this unclear and obtuse phrasing in §7.8 (suggestion provided)
Add Reply
Nicholas D Steeves
2019-11-07 22:00:02 UTC
Reply
Permalink
Package: debian-policy
Version: 4.4.1.1
Severity: normal

The full sentence in question is "This field should not be added
solely for purposes other than satisfying license or DFSG requirements
to provide full source code".

"solely for purposes other than satisfying" is the problematic
construction and should be rephrased for readability and clarity.

I suggest replacing the whole sentence with "The purpose of this field
is exclusively for cases where a package's license, or when DFSG
requirements, necessitate its presence; Built-Using should not be used
for any other purpose". This is much more clear and it flows
nicely into the next sentence "In particular, it should not be added
solely to enable finding packages that should be rebuilt against newer
versions of their build dependencies."

Regards,
Nicholas
Sean Whitton
2019-11-08 18:00:02 UTC
Reply
Permalink
Hello,
Post by Nicholas D Steeves
The full sentence in question is "This field should not be added
solely for purposes other than satisfying license or DFSG requirements
to provide full source code".
"solely for purposes other than satisfying" is the problematic
construction and should be rephrased for readability and clarity.
I suggest replacing the whole sentence with "The purpose of this field
is exclusively for cases where a package's license, or when DFSG
requirements, necessitate its presence; Built-Using should not be used
for any other purpose". This is much more clear and it flows
nicely into the next sentence "In particular, it should not be added
solely to enable finding packages that should be rebuilt against newer
versions of their build dependencies."
Thank you for this. I agree that the sentence is unnecessarily hard to
read. Perhaps you could propose a patch against policy.git.
--
Sean Whitton
Nicholas D Steeves
2019-11-08 20:20:02 UTC
Reply
Permalink
Post by Sean Whitton
Post by Nicholas D Steeves
I suggest replacing the whole sentence with "The purpose of this field
is exclusively for cases where a package's license, or when DFSG
requirements, necessitate its presence; Built-Using should not be used
for any other purpose". This is much more clear and it flows
nicely into the next sentence "In particular, it should not be added
solely to enable finding packages that should be rebuilt against newer
versions of their build dependencies."
Thank you for this. I agree that the sentence is unnecessarily hard to
read. Perhaps you could propose a patch against policy.git.
You're welcome :-) Done!
https://salsa.debian.org/sten-guest/policy/merge_requests/2


Cheers,
Nicholas
Sean Whitton
2019-11-09 15:00:01 UTC
Reply
Permalink
Hello Nicholas,
Post by Nicholas D Steeves
You're welcome :-) Done!
https://salsa.debian.org/sten-guest/policy/merge_requests/2
Hmm, this patch isn't what you proposed in your previous mail:

diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
index 140fdf1..8e4d98a 100644
--- a/policy/ch-relationships.rst
+++ b/policy/ch-relationships.rst
@@ -661,11 +661,10 @@ field in its control file:

Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)

-This field should not be added solely for purposes other than
-satisfying license or DFSG requirements to provide full source code.
-In particular, it should not be added solely to enable finding
-packages that should be rebuilt against newer versions of their build
-dependencies.
+This field's purpose is exclusively limited to cases where a package's
+license or DFSG requirements necessitate its use. In particular,
+it should not be abused as a convenient way to identify packages that
+require a rebuild against newer versions of their build dependencies.

.. [#]
While ``Build-Depends``, ``Build-Depends-Indep`` and

I'm not really keen on use of 'abused' as I think it's too aggressive.

I've also realised that "solely for purposes other than satisfying" is
actually doing some work here -- it's okay to add Built-Using for other
purposes so long as you are *also* using it to satisfy licensing
requirements. Not sure your proposal captures that. Any other
ideas for better phrasing?
--
Sean Whitton
Russ Allbery
2019-11-17 18:40:01 UTC
Reply
Permalink
Post by Sean Whitton
diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
index 140fdf1..8e4d98a 100644
--- a/policy/ch-relationships.rst
+++ b/policy/ch-relationships.rst
Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
-This field should not be added solely for purposes other than
-satisfying license or DFSG requirements to provide full source code.
-In particular, it should not be added solely to enable finding
-packages that should be rebuilt against newer versions of their build
-dependencies.
+This field's purpose is exclusively limited to cases where a package's
+license or DFSG requirements necessitate its use. In particular,
+it should not be abused as a convenient way to identify packages that
+require a rebuild against newer versions of their build dependencies.
.. [#]
While ``Build-Depends``, ``Build-Depends-Indep`` and
I'm not really keen on use of 'abused' as I think it's too aggressive.
I've also realised that "solely for purposes other than satisfying" is
actually doing some work here -- it's okay to add Built-Using for other
purposes so long as you are *also* using it to satisfy licensing
requirements. Not sure your proposal captures that. Any other
ideas for better phrasing?
How about:

This field should only be used when there are license or DFSG
requirements to retain the referenced source package. It should not
be added solely as a way to locate packages that need to be rebuilt
against newer versions of their build dependencies.
--
Russ Allbery (***@debian.org) <https://www.eyrie.org/~eagle/>
Sean Whitton
2019-11-18 00:10:01 UTC
Reply
Permalink
Hello,
Post by Russ Allbery
This field should only be used when there are license or DFSG
requirements to retain the referenced source package. It should not
be added solely as a way to locate packages that need to be rebuilt
against newer versions of their build dependencies.
Thanks, I think this is good -- would be good to hear from Nicholas too
though.
--
Sean Whitton
gregor herrmann
2019-11-18 21:00:02 UTC
Reply
Permalink
Post by Sean Whitton
Post by Russ Allbery
This field should only be used when there are license or DFSG
requirements to retain the referenced source package. It should not
be added solely as a way to locate packages that need to be rebuilt
against newer versions of their build dependencies.
Thanks, I think this is good -- would be good to hear from Nicholas too
though.
(Not Nicholas but) As a non-native speaker I think that's clear and
easy to read.

Cheers,
gregor
--
.''`. https://info.comodo.priv.at -- Debian Developer https://www.debian.org
: :' : OpenPGP fingerprint D1E1 316E 93A7 60A8 104D 85FA BB3A 6801 8649 AA06
`. `' Member VIBE!AT & SPI Inc. -- Supporter Free Software Foundation Europe
`- NP: Koko Taylor: Wang Dang Doodle
Nicholas D Steeves
2019-11-19 23:20:01 UTC
Reply
Permalink
Post by Sean Whitton
Hello,
[1] This field should only be used when there are license or DFSG
requirements to retain the referenced source package. [2] It should not
be added solely as a way to locate packages that need to be rebuilt
against newer versions of their build dependencies.
Thanks, I think this is good -- would be good to hear from Nicholas too
though.
I agree this is clear for people who already understand what it signifies,
but I don't think it's clear/accurate enough for a new contributor who
is struggling to understand Policy, because "retain the referenced
source package [singular]" seems to refer src:foo, if src:foo uses
Built-Using, and this isn't the case.

So:

(3) The Built-Using field should exclusively be used to satisfy license or
DFSG requirements, where those requirements stipulate that the
specific versions of build-time dependencies must remain available in
the Debian archive.

With further consideration I think (2) should be cut and replaced,
because it undercuts the clarity of this paragraph's premise. Eg: Clear
(1||3) "should" premise, but if a tree falls in a forest and no one
notices it fall then you can do this other thing (2) without anyone
noticing. If a maintainer uses the field for (1), then it's a non-issue
if they're also privately using it as a heuristic for (2). Thus I don't
think we need to say anything about the (2), because it's confusing for
people who don't already understand the discussed concepts.

Rather than (2), I think it would be better to refer to the general case
of how to use foo.buildinfo (or tooling that leverages buildinfo, or
some other method) to identify packages that need to be rebuilt.


Sorry for the delay replying!
Regards,
Nicholas
Sean Whitton
2019-11-20 05:20:02 UTC
Reply
Permalink
Hello Nicholas,

I am not sure what is going on with your (1), (2) and (3). Perhaps you
could propose your change in the form of a patch.
--
Sean Whitton
Nicholas D Steeves
2019-11-29 18:40:02 UTC
Reply
Permalink
Hi Sean,
Post by Sean Whitton
Hello Nicholas,
I am not sure what is going on with your (1), (2) and (3). Perhaps you
could propose your change in the form of a patch.
Those numbers refer to annotations in the quoted portion. IIRC you're
also using notmuch mode, so

[ x more citation lines. Click/Enter to show. ]

Needs to be activated to make them visible.

At any rate, I've submitted an update MR here (see previous email for
extended rationale):

https://salsa.debian.org/sten-guest/policy/merge_requests/3


Cheers,
Nicholas
Sean Whitton
2019-11-30 01:10:02 UTC
Reply
Permalink
control: tag -1 +pending

Hello Nicholas,
Post by Nicholas D Steeves
At any rate, I've submitted an update MR here (see previous email for
https://salsa.debian.org/sten-guest/policy/merge_requests/3
Thank you for preparing a patch. Unfortunately, I don't think that we
should be committing a stub paragraph to the Policy Manual.

The text of your patch outside of the stub paragraph doesn't read as
well at what Russ proposed. So I've gone ahead and committed Russ's
text to master, and marked it as closing this bug.

If you'd like to convert your stub paragraph into an actual patch,
against current master, please do share it for consideration.
--
Sean Whitton
Loading...