Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Ian Jackson <ijackson@chiark.greenend.org.uk>]

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.