Re: Why have a ChangeLog file if you already have commit messages?

["Havoc Pennington" <hp redhat com>]

Hi,

On 9/18/07, BJörn Lindqvist <bjourne gmail com> wrote:
> That is simply not true. Checkout KDE
> (http://websvn.kde.org/trunk/KDE/), Python
> (http://svn.python.org/view/python/trunk/) or SDL
> (http://www.libsdl.org/cgi/viewvc.cgi/trunk/) just to take three
> random projects that uses Subversion without ChangeLogs. They all have
> excellent and detailed commit messages that explain *why* something is
> changed.

Looking at some of those, it took me about 2 minutes to find plenty of
awful messages, some samples quoted *in their entirety* (from KDE and
Python):

"better use"

"Fix some error"

"upgdaded the test program"

"two mime encoding schemes"

"improved test/main program"

There are also plenty of good ones I saw quickly in the projects you
mention. However, even the good ones are kind of haphazard and
inconsistently-formatted.

I don't know the correlation vs. causation here. Maybe it's just that
people who don't like to write down change details also decide not to
use ChangeLog. May well have nothing to do with the technology and
everything to do with people.

I have lots of causation *theories*: using different editors in the
two cases; having examples of prior log entries to look at while
writing ChangeLog; having to do the commit message as an
'interruption' (like a dialog where you 'just click yes'); the format
of the ChangeLog encouraging people to write more (something for every
file at least).  But I can't prove any of these. Maybe none, some, or
all of them have some truth.

All I'm saying is, I don't see many ChangeLog entries that say "Fix
some error" and nothing else, and I found plenty of svn log messages
along those lines in a couple minutes clicking on the repositories you
linked to. This is an empirical conclusion. It's not a conclusion
about what should be or what is rational. It's a conclusion about what
happens in practice. (Obviously I didn't do a scientific study, if
someone is that bored, feel free.)

I don't know about git; since I don't understand why svn commit
messages don't work as well as ChangeLog does, I don't have an
understanding of whether git addresses the issue. It does look like
cairo's git logs are nice, so it's possible git addresses whatever the
key cause of svn log messages sucking might be. However, who knows.

I thought "what else uses git?" and decided to pick on Richard,
http://gitweb.freedesktop.org/?p=packagekit.git;a=log

I would say this log has many too-short entries in it. So there's
another data point.

btw, for svn.mugshot.org we don't use ChangeLog, and I think my log
messages are generally terrible on there.

The bottom line remains, we should write good messages. This can be
done with any technology.

My personal suspicion is that *some* people who don't want to use
ChangeLog secretly don't want to write a log message longer than a few
words, which is easier to get away with in an SCM log than ChangeLog.
Others avoiding ChangeLog have more noble motivations like the
elegance of not having two copies of the data, and they write nice log
messages in the SCM - more power to them.

Like code indentation style, many policies are fine, as long as you
have one that's applied consistently and well.

Havoc