[if you were CCed on this e-mail: this was because you seconded a previous version of the patch which included a recommendation which I have now dropped, and I hope you'll second the revised patch, further down this e-mail] Hello Jonathan, On Wed 25 Jul 2018 at 08:57PM -0700, Jonathan Nieder wrote: > Sean Whitton wrote: >> On Wed 25 Jul 2018 at 07:01PM -0700, Jonathan Nieder wrote: > >>> I share gregor's discomfort: I don't think we've thought this through. >> >> I too want Policy to be as correct as possible, but this bug has been >> open for ten years and one thing upon which there is certainly consensus >> is that the current text is not satisfactory. We should not let the >> perfect be the enemy of the good, at least in this case. > > *puzzled* I am not asking for Policy to be more correct. I'm asking > for it to provide guidance that can help me with my own packages. > > I'm providing the data point that for me, the proposed patch to this bug > does not work at all. It is way too restrictive, and the argument being > presented in favor of it is that I am allowed to ignore it. This > isn't about the perfect being the enemy of the good. This is about > wanting Policy to help me at all. > > Your response also feels dismissive. I've tried to be very concrete > in the input I provide here and I am wondering if this is appreciated > at all or if you consider my contributions to be a nuisance. Sorry about this. I thought that your e-mail was more tangential than it in fact is. This misunderstanding on my part was why I wrote an overly brief reply. Let me try to do better in this e-mail. > In that case, why don't we remove the requirement altogether? It's become clear that we do not have consensus on recommending that only the release notes be installed, and not also the changelog. And you have pointed out, importantly, that whether or not we can make such a recommendation has implications with regard to licensing. The issue is much more subtle than I had thought. We do have consensus on the rest of my patch, so far as I can tell (I don't think you or Bill or Gregor has raised any problems with it, aside from doubting whether we have consensus on the choice of naming). And further, ISTM that my patch is a decent basis upon which to have a discussion of whether and what we should recommend be installed and not installed. So what I now seek seconds for is the following. If someone would like to drive the inclusion of a replacement for the text I've dropped, that should be a new bug, with a clear statement of what is to be accomplished. diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst index 1de221f..e990f34 100644 --- a/policy/ch-docs.rst +++ b/policy/ch-docs.rst @@ -255,32 +255,45 @@ files may be installed into ``/usr/share/doc/package``. .. _s-changelogs: -Changelog files ---------------- +Changelog files and release notes +--------------------------------- Packages that are not Debian-native must contain a compressed copy of the ``debian/changelog`` file from the Debian source tree in ``/usr/share/doc/package`` with the name ``changelog.Debian.gz``. -If an upstream changelog is available, it should be accessible as -``/usr/share/doc/package/changelog.gz`` in plain text. If the upstream -changelog is distributed in HTML, it should be made available in that -form as ``/usr/share/doc/package/changelog.html.gz`` and a plain text -``changelog.gz`` should be generated from it using, for example, -``lynx -dump -nolist``. If the upstream changelog files do not already -conform to this naming convention, then this may be achieved either by -renaming the files, or by adding a symbolic link, at the maintainer's +If an upstream release notes file is available, containing a summary +of changes between upstream releases intended for end users of the +package and often called ``NEWS``, it should be accessible as +``/usr/share/doc/package/NEWS.gz``. An older practice of installing +the upstream release notes as ``/usr/share/doc/package/changelog.gz`` +is permitted but deprecated. + +If there is an upstream changelog available, it may be made available +as ``/usr/share/doc/package/changelog.gz``. + +If either of these files are distributed in HTML, they should be made +available at ``/usr/share/doc/package/NEWS.html.gz`` and +``/usr/share/doc/package/changelog.html.gz`` respectively, and plain +text versions ``NEWS.gz`` and ``changelog.gz`` should be generated +from them, using, for example, ``lynx -dump -nolist``. + +If the upstream release notes or changelog do not already conform to +this naming convention, then this may be achieved either by renaming +the files, or by adding a symbolic link, at the maintainer's discretion. [#]_ All of these files should be installed compressed using ``gzip -9``, as they will become large with time even if they start out small. -If the package has only one changelog which is used both as the Debian -changelog and the upstream one because there is no separate upstream -maintainer then that changelog should usually be installed as -``/usr/share/doc/package/changelog.gz``; if there is a separate upstream -maintainer, but no upstream changelog, then the Debian changelog should -still be called ``changelog.Debian.gz``. +If the package has only one file which is used both as the Debian +changelog and the upstream release notes or changelog, because there +is no separate upstream maintainer, then that file should usually be +installed as ``/usr/share/doc/package/NEWS.gz`` or +``/usr/share/doc/package/changelog.gz`` (depending on whether the file +is release notes or a changelog); if there is a separate upstream +maintainer, but no upstream release notes or changelog, then the +Debian changelog should still be called ``changelog.Debian.gz``. For details about the format and contents of the Debian changelog file, please see :ref:`s-dpkgchangelog`. > As for a sensible filename [for release notes], I don't see this > conversation having developed toward any consensus (unless > changelog.gz is that filename). One of the main motivations for getting a patch for this bug committed is that many maintainers are installing release notes instead of changelogs into changelog.gz, and this choice of location is clearly wrong. > The GPL contains the following: > > 5. Conveying Modified Source Versions. > > You may convey a work based on the Program, or the modifications to > produce it from the Program, in the form of source code under the terms of > section 4, provided that you also meet all of these conditions: > > a) The work must carry prominent notices stating that you modified > it, and giving a relevant date. > [...] > 6. Conveying Non-Source Forms. > > You may convey a covered work in object code form under the terms > of sections 4 and 5, provided that you also [...] > > If Debian modifies a package, we comply with this prominent notice > requirement using the Debian changelog. If the immediate upstream of > Debian modifies a package, then we ought to indicate when the > immediate upstream has modified the code, and the upstream changelog > accomplishes that. > > This isn't too unusual. The Apache license also contains a similar > provision about indicating that files have been modified, for example. Thanks again for this. IANAL so I really have no idea whether shipping the upstream changelog satisfies this requirement. But we can set this aside for a new bug. >> It is useful to be able to just type `zless >> /usr/share/doc/foo/known-filename` rather than having to look at the >> filenames and guess what they are. > > How do you do that on existing packages? This bug was opened because > there isn't a consistent practice. Right, sorry, I mean that once changelog.gz is meant to be changelog-like things and NEWS.gz is release notes-type things, I can run commands like that. >> This is far out of scope for this bug. > > If we set the filename and want people to type zless, then we are > imposing a format requirement (gzip). Policy already requires compressing all the files under discussion with ``gzip -9``. -- Sean Whitton
Attachment:
signature.asc
Description: PGP signature