XPost: linux.debian.bugs.dist

Package: debian-policy
Version: 4.1.1.1
Severity: normal

Section 4.4 explains quite a bit about debian/changelog, but doesn't really explain its purpose. I took its purpose to be recording history and driving automation - which led to some mistakes that might've been avoided. 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. This came as a surprise.

I'm not sure how this should be worded best, but I found a number of the comments on the thread to be helpful, especially [2].

Thanks,
Ross

[1] https://lists.debian.org/debian-mentors/2017/10/msg00145.html
[2] https://lists.debian.org/debian-mentors/2017/10/msg00178.html

-- System Information:
Debian Release: 9.1
APT prefers stable
APT policy: (500, 'stable'), (40, 'unstable'), (30, 'experimental') Architecture: amd64 (x86_64)

Kernel: Linux 4.9.0-4-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)

Versions of packages debian-policy depends on:
ii libjs-sphinxdoc 1.4.9-2

debian-policy recommends no packages.

Versions of packages debian-policy suggests:
pn doc-base <none>

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

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

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

Ross Vandegrift <ross@kallisti.us> writes:

Section 4.4 explains quite a bit about debian/changelog, but doesn't
really explain its purpose. I took its purpose to be recording history
and driving automation - which led to some mistakes that might've been avoided. 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. This came as a surprise.

Separate than the point that Policy could probably stand to say something
a little more concrete about the purpose of debian/changelog, I suspect
this came out of the recurring discussion of whether to include unreleased versions in debian/changelog.

It's probably worth noting here that while debian-mentors has converged to
a very strong consensus that unreleased versions of packages should not
appear in debian/changelog, the consensus about that in the broader
project is nowhere near as strong. This is therefore a rule that you
pretty much have to follow if you want people to sponsor your uploads, but Debian Developers do not follow it universally.

Some people in debian-mentors will make very absolute statements about
never including unreleased versions in debian/changelog and always consolidating versions, and will give the impression that literally
everyone in Debian holds this view. This is not really the case. It's
*most common* to consolidate versions, and usually there's no point in
keeping entries for unreleased versions, but this isn't a universal rule followed by every experienced Debian maintainer, and there are times when retaining entries for unreleased versions is useful (there were non-Debian releases of the package, for instance, or there's something about the development path that the maintainer felt was important to document).

To include rules about this in Policy would indicate not just that there's
a best practice, but that it's also important enough to tell people that
they have to follow it. I've always been dubious of this, mostly because
I don't see a lot of *harm* in including unreleased versions when the maintainer wants to do that. All the tools cope with this
(apt-listchanges shows all the entries, for instance), and so far as I can tell, the primary objection is basically aesthetics.

I care as much about aesthetics as the next perfectionist free software developer, but in general I prefer to see a higher bar for inclusion in
Policy than aesthetics. As long as variance of practice doesn't *break* anything, I'd generally prefer to keep it out of Policy and in other, more informative guides to best practice, such as the Developer's Reference.

--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

On Wed, Oct 18, 2017 at 08:48:28PM -0700, Russ Allbery wrote:

Some people in debian-mentors will make very absolute statements about
never including unreleased versions in debian/changelog and always consolidating versions, and will give the impression that literally
everyone in Debian holds this view. This is not really the case. It's
*most common* to consolidate versions, and usually there's no point in keeping entries for unreleased versions, but this isn't a universal rule followed by every experienced Debian maintainer, and there are times when retaining entries for unreleased versions is useful (there were non-Debian releases of the package, for instance, or there's something about the development path that the maintainer felt was important to document).

What actually matter is that the .changes file include the relevant
extract from the changelog and do not miss packaging change because
they where listed in unreleased versions and dpkg-genchanges -v
was not used properly.

Cheers,
--
Bill. <ballombe@debian.org>

Imagine a large red swirl here.

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

control: tag -1 +moreinfo

Hello Ross,

On Tue, Oct 17 2017, Ross Vandegrift wrote:

Package: debian-policy Version: 4.1.1.1 Severity: normal

Section 4.4 explains quite a bit about debian/changelog, but doesn't
really explain its purpose.

Have you seen Developer's Reference 5.2? That gives more detail. I am reluctant to duplicate that in Policy.

--
Sean Whitton

--=-=-Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAlnoDHUACgkQaVt65L8G YkAoBw/+KH4g+Xv1J/mmk79fObQES78FfhMV9qmao21VLg5K9I6LIxF0TVGKx1aB o+vs3CPXNHtOrEma3qzUpACIJziXo6kGcs+h1WfrJPUGj1NMARh1QKNurn9Bc50m wOsOgIUeJgvOk8XqXej52mjIn2OF5WNhIt54+ntsZK1iq0XUMVv5UGuwD0AxJg9T vz1JNjHQqfb04M6qrYmuwf9S30r+HqGSUvU70SB4+j2zrKnrdR8HBozeMmjdSm/Y peNJST59SAS6dMN3yWZRrbyi7EEwoYMxT6QRJ+64S37phbhSP1Hyv2eWxnQkkLv2 CkeA75YpwmI4lnETvEhc14R9+v7ujMPN4L29hLVu32zLmKampKTF1XUbFssgrsa/ a7gEPMKBNs6Urc7QCWE1EKuY4pX1Cgn8mZeG//Ocv9pJw7Mp7nuU/6VCxEletcXI Rt4yqKh/N7Ughvv/D6wdJoVSMZyLZYBwQmIWIB/kDQVZRgh/VhBSc/etsLL4oIAs /XGSgQTPZiQTTvysCcxJgvyVwwohDrOVdMhO6fbQK9o/8KyR3aYs4ZAQlWZ32xoj 1NcRGbGE1bdwyMl3f4dTaGx7BxrdC+S0Dh4NbqgCUh1hl/g3/izPeKAOgK4C5axa aMg6sEBtrxSpc0AvmlUw03wghhAmfO2tr1phnmyNvjRKj9DMGHE±zb
-----END PGP SIGNATURE-----

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

Sean Whitton <spwhitton@spwhitton.name> writes:

On Wed, Oct 18 2017, Russ Allbery wrote:

It's probably worth noting here that while debian-mentors has
converged to a very strong consensus that unreleased versions of
packages should not appear in debian/changelog, the consensus about
that in the broader project is nowhere near as strong.

I was active on -mentors relatively recently and I don't think I
understand what you mean when you say "unreleased versions of packages
should not appear in debian/changelog".

Do you mean that successive uploads to mentors.debian.net are expected
to re-use the same Debian version number?

My impression of discussion on debian-mentors over the past few years is
that most of the people active in sponsoring have as a requirement that
all changelogs from versions of a package that weren't uploaded to Debian
be consolidated and the version of a new package upload, as finally
uploaded to the archive, always be one higher than the last version
uploaded to Debian proper.

This makes a lot of sense in the context of nearly all packages that flow through sponsorship, and I realize it's a correction for the very early
days of mentors.debian.net when people tended to bump the version for
every package they made available for review, and there were a ton of
changelog entries generated from back and forth discussions with mentors
that never saw the archive. That's obviously not very useful.

But I feel like that sensible guideline hardened, during repeated
discussion, into something that's sometimes presented as a hard and fast
rule that one should *always* do this in Debian packaging. Yet, I've seen
a lot of cases where experienced DDs retain intermediate unreleased
versions in the changelog for various reasons, so I'm a bit dubious of it
as a concrete rule, even though it almost always makes sense in the
specific context of sponsored uploads.

--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

Bill Allombert <ballombe@debian.org> writes:

What actually matter is that the .changes file include the relevant
extract from the changelog and do not miss packaging change because they where listed in unreleased versions and dpkg-genchanges -v was not used properly.

Yes, indeed, that's a very good point, and I'm not sure whether we've adequately documented that wrinkle.

--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

Hello Russ,

On Wed, Oct 18 2017, Russ Allbery wrote:

It's probably worth noting here that while debian-mentors has
converged to a very strong consensus that unreleased versions of
packages should not appear in debian/changelog, the consensus about
that in the broader project is nowhere near as strong.

I was active on -mentors relatively recently and I don't think I
understand what you mean when you say "unreleased versions of packages
should not appear in debian/changelog".

Do you mean that successive uploads to mentors.debian.net are expected
to re-use the same Debian version number?

--
Sean Whitton

--=-=-Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAlnpNz4ACgkQaVt65L8G YkCV/w/+Mugk0SvQJekoKSIyyRAzqM/tYmo+x/xzbrBlpLHnTP+AsnBLr5zyOujM FhxSuaIHHYXK1iGiwPXlWqaqK7DxRnM7npDRGCdV2gttb/lFh2Y3pDDPy0Y1Mcjx HQJhofiyP6yfa3TCOuK3oKCMfe8389ywCN0qnftLMj6duH0x6wjGuP1GyVWSTkat JIu6mUi7PlxS4w86Q6kyze1ZrElQ4Bthh8vdMMkjXfsuM3recZwev/ZuGxZ2rHQb DgguECmVlQUZHEH48+PE12z/0LZ0p52Dpm4DhrJKLSAtHaJfiW1FYkvCoT2xEDWg MSRkvSbokdD9/bIShN3BiGUGOIwhiqpcmz3vNhKnuJgcZMLFMZj1JCLgR6cc9Cy0 MLPE2JMmCegPkoWxPSTIZeQyksNNa1EFwtgp7zq4r/H9R0mEZn2DKo2bfVCkwo1x mZ9Z6MiNgqx5Taxvvm21SJDTlNUk9ItC51rdDDYBI2KZ95vHFvs8YnmWlezwSG+b wGsoeaYd+8kyY22n8p1P9f71gaS7Qb+8Ti3Cc/z523GllYawLpF0Y1nXHy5T0Vct FHBchpsxB+NxAczvxhT4/HHpdF3p2At99JUuDem42GladrZ2WOTD72I/7jbCXDIX y3V5jJC8+MCKVXvn0vF0ZTxphdD/8yIQDuUU6g58J6D+3ZH3ebY=Kjh8
-----END PGP SIGNATURE-----

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

Hello,

On Thu, Oct 19 2017, Russ Allbery wrote:

My impression of discussion on debian-mentors over the past few years
is that most of the people active in sponsoring have as a requirement
that all changelogs from versions of a package that weren't uploaded
to Debian be consolidated and the version of a new package upload, as
finally uploaded to the archive, always be one higher than the last
version uploaded to Debian proper.

This makes a lot of sense in the context of nearly all packages that
flow through sponsorship, and I realize it's a correction for the very
early days of mentors.debian.net when people tended to bump the
version for every package they made available for review, and there
were a ton of changelog entries generated from back and forth
discussions with mentors that never saw the archive. That's obviously
not very useful.

But I feel like that sensible guideline hardened, during repeated
discussion, into something that's sometimes presented as a hard and
fast rule that one should *always* do this in Debian packaging. Yet,
I've seen a lot of cases where experienced DDs retain intermediate
unreleased versions in the changelog for various reasons, so I'm a bit dubious of it as a concrete rule, even though it almost always makes
sense in the specific context of sponsored uploads.

Thanks, I see what you mean.

I suspect that this was not exactly what the original submitter was
asking about, but hopefully he'll reply to clarify.

--
Sean Whitton

--=-=-Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAlnqiZkACgkQaVt65L8G YkANVRAAj+XyTOchO6o2+vjdUb6Z2LSpMtKa+FZS2OVxw9ojhK1VxyF47Jk4kcKx WZMJ+wHDOTDj5/AWh2sT2nRZwpXkCfvxabp8Ck1sRjCjMIyx7GgRyq6BCLICvV/f N0e6nFusLKWvh5CR4vXoJpJehxzYL1p5TyHyGDCTnjEX+qjRXAwNmK63qOlZvrpL 8Ozz+LK31s0Ia9H2okRoIO/NDpbp3Zd9gyUTTuNjQNFdDvVDshe9frYWAu8cCxaT qMsNkASWR4w5P7mr7j90oIjbDXQvDbqLQKbvR80xZOM5yMqywyTiOlifcIv1GTzj b33r0U/LHsF3DjYttkHdQ030a/XqvC2uSsea+BhjAVm7lQ48YP01bDw9QHy3M0Jd DyT8QoSZQX0AWmRzoxpA7MfhD+3+XOEtq/rNjfRgEr/v8BoJB5a/DsrLfC5jekgw D8JBHVuxnUFRmVLiwmhKf0Hf5qdQi7VnlyK1LAyb3/Td8gYE5/YWTXDf3dNS95sU GNEYG1LMJ9NhsP1uGSJ2ur916DGxm2IW3CP298OfBbAu2StlxX3PNUSXNNBUPqZ6 Xx7v350w15MoTMwN0TE04+j1xEm/vf2SjDJrlWNinCE209UnMMll8NXJmh10Dh2f gIWWjG3/QqkVgoSigaSWUL2+DPKZnl/gHjnBXBd+HCF8tuolrvc=7Ml0
-----END PGP SIGNATURE-----

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

On Wed, Oct 18, 2017 at 08:48:28PM -0700, Russ Allbery wrote:

Separate than the point that Policy could probably stand to say something
a little more concrete about the purpose of debian/changelog, I suspect
this came out of the recurring discussion of whether to include unreleased versions in debian/changelog.

Well yes, but this bug is about the first issue only. If they can't be separated, or if there's no concensus regarding purposes for
d/changelog, this should probably be closed.

Ross

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

XPost: linux.debian.bugs.dist

On Wed, Oct 18, 2017 at 07:22:45PM -0700, Sean Whitton wrote:

On Tue, Oct 17 2017, Ross Vandegrift wrote:

Package: debian-policy Version: 4.1.1.1 Severity: normal

Section 4.4 explains quite a bit about debian/changelog, but doesn't
really explain its purpose.

Have you seen Developer's Reference 5.2? That gives more detail. I am reluctant to duplicate that in Policy.

I have, it does, and that's a reasonable reluctance. But I don't see
anything there that would tell a new contributor about the intended
audience(s) of debian/changelog.

It could be that this bug would be better filed against Developer's
Reference, if that would be a better location.

Ross

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)