On Sun, Jul 22, 2018 at 11:35:48AM +0800, Sean Whitton wrote: > control: tag -1 +patch > > Hello all, [...]
Thanks for working on this and thanks for including your rationale about the tradeoffs you had to make. While I still retain my aging view on this which isn't perfectly described by your proposal I'll myself take the advice from 'perfect is the enemy of good' and see that we would gain by having these improvements in sooner rather than later. Thus, Seconded. > > 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
