Bug#459427: changelog vs. NEWS handling
Package: debian-policy
Version: 3.7.3.0
Severity: normal
There is some lack of clarity in the policy or perhaps some confusion among
packagers and thence inconsistencies among packages regarding the handling of
upstream changelog files. Policy says that upstream changelogs should be
installed as /usr/share/doc/package/changelog.gz. Many packages, however, come
with two kinds of changelogs: a source-level list of changes directed at
developers, often called ChangeLog in a GNU-type package, and a user-level list
of changes, sometimes called release notes, often in a file called NEWS in a
GNU-type package.
Debian packages appear to handle this in different ways: Some take the policy
literally and install the ChangeLog as /usr/share/doc/package/changelog.gz and
then install NEWS as additional documentation in /usr/share/doc/package/NEWS.gz
or whatever the file is called in the particular case. Sometimes the source
package doesn't come with a useful changelog, so they install NEWS or the
release notes as /usr/share/doc/package/changelog.gz; others would then not
install a "changelog" and install /usr/share/doc/package/NEWS.gz or some other
name instead.
This has two major problems: I think that installing a source-level change list
is hardly ever useful for a binary package. Most users would probably rather
read the release notes, but these are currently not be found at a uniform
location. The intent behind all this was probably to give the package user a
list of user-level changes. So in that sense most packages do a less than
ideal job at the moment.
I can think of three possibilities to address this:
1. Clarify the policy that a source-level changelog should be installed as
/usr/share/doc/package/changelog.gz and user-level change lists/release notes
should be installed as /usr/share/doc/package/NEWS.gz, whichever of these is
available and deemed useful. This has the advantage that it is
backward-compatible with respect to the changelog handling, and it would allow
users to find the release notes under the familiar name "NEWS". It would also
be somewhat consistent with the GNU names for these files and the handling of
changelog.Debian vs. NEWS.Debian.
2. Modify policy to say that source-level changelogs should not be installed
unless there is some overriding reason. Also say that user-level release notes
should be installed as /usr/share/doc/package/changelog.gz. This has the
advantage that the currently used name "changelog" is preserved, but the
disadvantage would be that it would take on a new meaning for many packages.
It would also create an inconsistent naming scheme compared to the handling of
changelog.Debian vs. NEWS.Debian.
3. Modify policy to say that source-level changelogs should not be installed
unless there is some overriding reason. If they are installed, they should be
installed as /usr/share/doc/package/changelog.gz. Add to policy that
user-level release notes should be installed as /usr/share/doc/package/NEWS.gz.
This has the advantage that it would preserve the meaning of the "changelog"
file for most packages, but most packages could opt to drop them since they are
probably useless in most cases. It would also create a new uniform policy for
installing upstream release notes, which are currently handled inconsistently,
and it would use the familiar name "NEWS" for that file, consistent with
GNU-type packages and the name NEWS.Debian.
Reply to: