(debian-policy.info)Changelog files and release notes

---

Prev: Examples Up: Documentation

---

Enter node , (file) or (file)node

12.7 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 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.
(1)

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 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 Note: Debian changelog; debian/changelog.

   ---------- Footnotes ----------

   (1) Rationale: People should not have to look in places for upstream
changelogs merely because they are given different names or are
distributed in HTML format.