12. Documentation - 12.7. Changelog files and release notes - 《Debian Policy Manual v4.5》

12.7. Changelog files and release notes

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. 10

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

It is not very hard to write a man page. See the Man-Page-HOWTO, man(7), the examples created by dh_make, the helper program help2man, or the directory /usr/share/doc/man-db/examples.

Supporting this in man often requires unreasonable processing time to find a manual page or to report that none exists, and moves knowledge into man’s database that would be better left in the file system. This support is therefore deprecated and will cease to be present in the future.

man will automatically detect whether UTF-8 is in use. In future, all manual pages will be required to use UTF-8.

At the time of writing, Chinese and Portuguese are the main languages with such differences, so pt_BR, zh_CN, and zh_TW are all allowed.

Normally, info documents are generated from Texinfo source. To include this information in the generated info document, if it is absent, add commands like:

@dircategory Individual utilities
@direntry
* example: (example).  An example info directory entry.
@end direntry

to the Texinfo source of the document and ensure that the info documents are rebuilt from source during the package build.

The system administrator should be able to delete files in /usr/share/doc/ without causing any programs to break.

Please note that this does not override the section on changelog files below, so the file /usr/share/doc/package/changelog.Debian.gz must refer to the changelog for the current version of package in question. In practice, this means that the sources of the target and the destination of the symlink must be the same (same source package and version).

Rationale: The important thing here is that HTML documentation should be available from some binary package.

In particular, /usr/share/common-licenses/Apache-2.0, /usr/share/common-licenses/Artistic, /usr/share/common-licenses/CC0-1.0, /usr/share/common-licenses/GPL-1, /usr/share/common-licenses/GPL-2, /usr/share/common-licenses/GPL-3, /usr/share/common-licenses/LGPL-2, /usr/share/common-licenses/LGPL-2.1, /usr/share/common-licenses/LGPL-3, /usr/share/common-licenses/GFDL-1.2, /usr/share/common-licenses/GFDL-1.3, /usr/share/common-licenses/MPL-1.1, and /usr/share/common-licenses/MPL-2.0 respectively. The University of California BSD license is also included in base-files as /usr/share/common-licenses/BSD, but given the brevity of this license, its specificity to code whose copyright is held by the Regents of the University of California, and the frequency of minor wording changes, its text should be included in the copyright file rather than referencing this file.

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.