Russ Allbery:
Bill Allombert <ballo...@debian.org> writes:
[...] Quite a lot of Policy is of the general format "here's a bunch of
complex things you need to do, wait, never mind, just use debhelper, go
see its documentation for the configuration files you should use instead"
and some of the rest of Policy is "here's a bunch of complex things you
need to do but if you follow these instructions instead of using debhelper
your package will be buggy." This is not ideal!
I think there's a lot of appeal of having a thorough specification for
what debhelper is supposed to be doing. It would enable future
competition around better packaging helpers (and I do think debhelper will
not be the last word). But I also want to be realistic about whether
we're really capable of maintaining that specification.
--
Russ Allbery (r...@debian.org) <https://www.eyrie.org/~eagle/>
Indeed. I have had the same challenge with the Policy.
I had a look at the introduction section of Policy to check who the
target audience is. I cannot find an explicit mention of the target
audience. I suspect there is a conflict here on the content because we
have different audiences in mind for the Policy and the Policy does not
seem to be explicit here.
If the target audience is package maintainers, then 100% of all debian
contributors should read it. Then we need "simple and easy to
understand" language and examples, because we want *everybody* to
understand this. I agree with Russ that long winded sections of "here
is how you do this manually but really just use debhelper" is directly
counter productive to this audience.
If it is cross-package integration, are we targeting the ones
integrating or the ones providing the integration points? If it is
both, then for more complex topics, it would make sense to split the
topic into two. One for consumer and one for the provider of the
integration, because for the consumer it will probably boil down to
"install path at $X in your deb and run tool $Y" and then the consumer
can skip the provider section as "not relevant".
There is a separate here in whether the Policy editors have the
capacity to maintain the documentation for the provider side of the
integration points for all the integrations. I think this is where Russ
is arguing that we do not that capacity. If so, it would also make
sense to explicitly cut *out* that side of from policy in the Scope
section. Maybe along the lines of "The Policy does not document the
provider side of integration points directly. Instead, we provide links
to the external documentation where available.".
If the target audience is tool-chain maintainers, then only 5-10 people
need to read the policy and the entire document + related process seems
completely over-engineered. But then, for the same reason, I suspect
this is an unlikely target audience for the Policy.
Either way, I think the root problem is that we are not all agreeing on
scope and audience for the Policy. Until resolved, we can argue forever
about whether X belongs in Policy.
Best regards,
Niels
PS: I also have other things to say about the concrete topic, but I will
leave that for a later mail. I think the point above is so important
that it should not be diluted with other topics.
