Web lists-archives.com

Re: changelog practice, unfinalised vs UNRELEASED vs ~version

Simon McVittie <smcv@xxxxxxxxxx> writes:

> I think you're the only person I've ever seen using unfinalized
> changelog entries for Debian packages.

I think the fact you don't know we're using this workflow isn't very
informative :-)

> Broadly, the two extremes of workflows for Debian packages' changelogs
> maintained in git seem to be:
> * Write the changelog as you go along: each commit includes its own
>   Debian changelog entry.

Yes. The Debian changelog is documentation, and describes a particular
state of the package. When that state changes, it's a fine practice to
immediately update the documentation describing the package.

>   This works fine if every commit is final and immutable and is sent
>   directly to the master VCS immediately, but works very poorly if you
>   are proposing commits for someone else to merge at a later date -

I don't see how this complaint is any different from the need to merge,
for example, changes to API documentation and test cases that accompany
a functional change.

> * Write the changelog later: each commit just has a commit message
>   in a normal git way, and its debian/changelog is out of date.

For the record, I don't have anything against that workflow either. I
disagree that it should be preferred.

> I'm concerned that the first model is optimized for people who know
> Debian as well as you do, and do not need pre-commit review because
> they get everything right first time.

That concern is, I'd think, addressed by realising changes are not
immutable; a new change is merely an additional commit away. Resolving a
conflict in documentation isn't especially onerous compared with the
general resolution of conflicts in a collaborative code base.

I'm in agreement with Ian that the “write the documentation (including
the changelog) along with the change it describes” workflow should have
full support from our tools.

 \      “We tend to scoff at the beliefs of the ancients. But we can't |
  `\        scoff at them personally, to their faces, and this is what |
_o__)                                         annoys me.” —Jack Handey |
Ben Finney