Sean Whitton writes ("Bug#459427: Patch seeking seconds on changelog vs. NEWS
handling"):
> +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.
I think part of the difficulty we are having with this is by failing
to have a kind of contextual introduction.
How about:
Upstreams provide information about changes between upstream ersions
in a variety of formats and with a variety of content. Typically
there are two distinct kinds of change informatiion:
* Release notes style: describes user-visible changes such as new
features, backwards compatibility issues, and perhapz significant
bugfixes. Examples: [...]
* Code changelog style: lists all changes made to the source code,
even ones which are not user-visible, often by reference to
source code filenames. Examples: [...]
Release notes are useful to users. If available, they should be
installed as /usr/share/doc/PACKAGE/NEWS.gz.
Code changelogs are not very useful without the source code. They
should not normally be installed in the binary package unless this
is required by the package's licence. When they are installed, they
should be installed as /usr/share/doc/PACKAGE/changelog.gz.
Note that terminology and filenames for these vary. We want to
provide Debian's users with consistency across packages, so you
should rename the file(s) according to their contents. Some
language- or domain-specific packaging teams have more specific
policies. You should follow them, so that all packages in a
particular domain are consistent.
If information provided by upstream does not fit neatly into these
categories, you should use your best judgement. All documents that
are useful to users should be in the binary package.
Ian.
