GNU ChangeLogs, commit logs and commits
Hi,
Ok, this has been going on for some time now, let's discuss and get a
conclusion. But first some background:
When dpkg got handed-over to us, we switched it to svn, for which GNU
ChangeLogs are good (maybe just a bit less than for CVS, though) as
«svn log» is pretty slow and needs to be online, more so when trying to
dig out when something got changed as they provide precision up to
function and variable name level, but for GNU ChangeLogs to be really
useful, they need to have been consistent and thorough during all its
history, something that cannot be said for dpkg, which even changed
format few times.
GNU ChangeLogs are also good to track contributions on lesser VCS which
do not properly store authorship, for example for copyright purposes. And
personally in some ways I like the discipline they impose when writting
them, which makes you realize if the changes you are about to commit
actually belong on the same logical unit.
On the other hand they are also pretty annoying and repetitive when doing
lots of refactoring and cleanup. And when merging or rebasing patches, as
the dates get out of order.
With the switch to git, I guess all of us stopped relying on the
ChangeLogs at some point to do commit archeology, and started using
mostly exclusively git commands, like «git log --stat», «git log -p»,
«git blame», etc.
The current way the several change logs are used is this:
debian/changelog - Major changes and user visible changes, NEWS like
ChangeLog - Supposedly only what has changed, and not why (GCS)
commit log - Narrative explanation or a copy of the ChangeLog entry
Both debian/changelog and ChangeLog are the cause of most of our current
merge conflicts, and the information is not actually the same on each of
those, but it does overlap.
So, I think if we have to switch, we should drop completely the GNU
style ChangeLog format and use normal git style commit logs.
,---
possible-subsystem: short summary
Narrative explanation of the change if needed.
`---
Rename the current ChangeLog files to ChangeLog[.-]old or whatever and
then simply generate the whole new ChangeLog at «make dist» time, from
the point were we switched, with something like:
,---
.PHONY: ChangeLog
ChangeLog:
git log -C --stat 1.15.0.. >$@
`---
I'd leave the discussion about debian/changelog conflicts for later.
Let's do a step at a time.
Something I'd like us to adhere to, though, is:
* Short summary should be distinguishable:
- Stuff like “Updates” is not useful.
* Informative and clear commit logs:
- No rants, etc (those are not blog posts :).
* Correct attribution information:
- Use --author when committing on behalf of someone else.
- Probably use more Foo-by: pseudo-fields.
* Small logical unit commits (if it cannot be described fully in the
short summary, then there's probably too many changes):
- Others do not get put off by monster commits, or trying to mentally
untangle the unrelated changes in their minds.
- Makes it easier to verify for correctness, avoid regressions, etc.
- Makes it easier to revert or cherry-pick if needed.
regards,
guillem
Reply to: