Sean Whitton <spwhit...@spwhitton.name> writes: > > 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`. >
seconded d
