Re: Is it time to drop ChangeLogs?

[Stefan Monnier <monnier@iro.umontreal.ca>]

> I'd like to open this up to discussion on emacs-devel, so that we hear from
> our other developers. What do you all think about ChangeLogs, and their value
> to you in your work on Emacs?

I couldn't care less about ChangeLog *files*, really.

I think it makes sense to provide them in tarballs (to replace the Git
metadata), but I've personally stopped using them years ago when "bzr
log" started being fast enough.

But OTOH I strongly oppose getting rid of the ChangeLog format in commit
messages.  My experience with commit messages is that it's very
difficult for people to know what should go in a commit message
(especially so for less experienced coders, but even for experienced
coders it's difficult to guess what information will turn out to be
important).

The ChangeLog format's rules gives a very good baseline for that.
Even if some of that info seems redundant, the act of describing all the
parts that are changed, encourages the coder to pay attention to every
part of the diff she's about to commit.

The original ChangeLog format lacked a high-level description of the
intention behind the changes, so the rules we currently use in Emacs is
to use something of the form:

    <One line summary>

    <High-level description of the purpose of the change>

    <ChangeLog-style details>

If we were to drop the "ChangeLog-style details", we'd end up with very
little guidance as to what to put in the commit message, so we'd have
even more trouble getting contributors to start providing acceptable
commit messages.

My experience (when trying to figure out, years later, why such and such
line of code was changed in that particular way) is that ChangeLog-style
details don't always give you the info you want, but at least they tend
to say *something* about your particular line (because they have to talk
about every part of the diff), whereas the high level description is
too often too high-level and hence not detailed enough for that.


        Stefan