Hello Bill, On Mon 23 Jul 2018 at 12:29PM +0200, Bill Allombert wrote:
> The issue is that the recommendation does not include a rationale, and > it seems to me the rationale is based on an implicit definition of > changelog which is not communicated either (or more precisely, it is > based on the undocumented assumption that if a package includes both a > changelog and a NEWS, the changelog is a source-level one, which is not > always the case). > > So the maintainer has no basis to decide whether to ignore the recommendation. > > So I would suggest policy to define precisely the kind of sourcelevel > changelog > that is not useful to the binary package user and recommend not to > include them, with a rationale. > > It is always better for policy to state its goal explicitely. Thank you for the explanation. I disagree, however, that Policy should be completely explicit here. What we are doing is making a recommendation based on a division of these files into two classes. However, since there are all sorts of different files that there could be in upstream sources, package maintainers are going to have to make a judgement about what kind of files they have on their hands. It's still useful to have it pointed out to them that changelogs are less useful than release notes in most cases. I've made the following change on my branch (that I do not believe invalidates any seconds) in response to your feedbacK: diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst index 1503ed8..46c51cf 100644 --- a/policy/ch-docs.rst +++ b/policy/ch-docs.rst @@ -273,7 +273,10 @@ If there is no release notes file available, but there is an upstream changelog, it should be accessible as ``/usr/share/doc/package/changelog.gz``. If there are both upstream release notes and an upstream changelog available, it is recommended -to install the former but not the latter. +to install the former but not the latter. This recommendation applies +when the upstream changelog would not be useful without the full +upstream source, and so not useful in the binary package, but only in +the source package. If either of these files are distributed in HTML, they should be made available at ``/usr/share/doc/package/NEWS.html.gz`` and -- Sean Whitton
signature.asc
Description: PGP signature
