Re: changelog practice, unfinalised vs UNRELEASED vs ~version
- Date: Mon, 13 Feb 2017 09:42:32 +1100
- From: Ben Finney <bignose@xxxxxxxxxx>
- Subject: 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
> 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 |