Bug#878967: debian-policy: clarify purpose of debian/changelog

[Simon McVittie <smcv@debian.org>]

On Tue, 17 Oct 2017 at 23:06:29 -0700, Ross Vandegrift wrote:
> During a
> recent thread on mentors [1], I learned that the purpose is to provide a human
> readable list of changes between released versions of Debian.

Between released versions of the package in Debian, rather than versions
of Debian itself. If Debian 9 contained foo_1-1, and you upload foo_2-1,
foo_2-2 and foo_4-1 to unstable for Debian 10, then the changelog should
look something like this:

    foo (4-1) unstable; urgency=low

      * New upstream release 3
        - reticulate splines correctly (Closes: #654321)
      * New upstream release 4
        - fix regression caused by better spline reticulation

     -- Maintainer <email>  Date

    foo (2-2) unstable; urgency=low

      * Drop obsolete transitional package (Closes: #123456)

     -- Maintainer <email>  Date

    foo (2-1) unstable; urgency=low

      * New upstream release

     -- Maintainer <email>  Date

    foo (1-1) unstable; urgency=low
    ...

If a version was never released to Debian, then as far as Debian is
concerned, that version never really existed. I think perhaps that's the
key point you were previously missing? The changelog lists the changes
from the perspective of a consumer of the package, not the maintainer,
and a typical consumer of the package has never had the opportuniy to
use or identify the unreleased version.

For example, in
https://anonscm.debian.org/cgit/pkg-games/ioquake3.git/commit/?id=bafbfb0e12fbd73663f88c125eb012700613dcca
because version 1.36+u20170720+dfsg1-2 was never uploaded to Debian,
the new version 1.36+u20170803+dfsg1-1 modifies the UNRELEASED changelog
entry for the new upstream snapshot, while in
https://anonscm.debian.org/cgit/pkg-games/ioquake3.git/commit/?id=05e95ddbf5f6c8f14c45f7fc0e0c91fb6294a347,
because nothing had changed since the previous version was uploaded,
the new upstream snapshot starts a new changelog entry. I believe what
I'm doing there represents best-practice (except for the bit where
I'm packaging snapshots from git instead of actual releases, which is
a necessary evil in this case).

    smcv