control: tag -1 +patch Hello all, David Bremner and I took a look at this bug this morning at DebCamp and I realised that I had been missing something (which Russ had actually pointed out in an older message): lots of packages already install a package's NEWS file as /usr/share/doc/foo/NEWS.gz. This means that making this change would be documenting an existing practice rather than having Policy drive a change to practice. So this removes the reasons that I had for thinking that debhelper should change first. We still have the problem that packages installing the NEWS file to /usr/share/doc/foo/changelog.gz would be made buggy by a change that simply required the NEWS file to be installed to /usr/share/doc/foo/NEWS.gz. But Bill pointed the way to a solution to this: word Policy to allow both practices, but mark one as deprecated. Looking through some of the messages to this bug, I think that the following change is minimal enough to avoid too much controversy and bikeshedding, so I'm seeking seconds for it. Two further notes about my patch: - The patch defines what release notes are, but does not define what a changelog is. This is not a regression, because Policy does not currently define what a changelog is. And in fact the problem is hard, because the way that dev.ref. recommends we use debian/changelog makes it sound like it is a release notes file, not a changelog. So I think we should put the issue aside as a separate change and not try to address it in this bug. - I have chosen to include the recommendation not to install both the changelog and the release notes if both are available. I've done this using the term 'recommended', which is the weakest requirement Policy can impose; maintainer discretion is allowed. We do seem to have something of a consensus on this, and maintainers who do disagree can ignore the recommendation. The argument for including the recommendation is that a changelog is not very useful in a binary package, except as a fallback when no release notes are available. If you're going to dig into an upstream changelog you will do so alongside a copy of the upstream source. So distributing the upstream changelog in only the source package, and not the binary package(s), makes most sense. > diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst > index 1de221f..1503ed8 100644 > --- a/policy/ch-docs.rst > +++ b/policy/ch-docs.rst > @@ -255,32 +255,48 @@ 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 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. > + > +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`. -- Sean Whitton
Attachment:
signature.asc
Description: PGP signature