Re: Why have a ChangeLog file if you already have commit messages?
- From: "Sean Kelley" <svk sweng gmail com>
- To: "Havoc Pennington" <hp redhat com>
- Cc: Federico Mena Quintero <federico ximian com>, "desktop-devel-list gnome org" <desktop-devel-list gnome org>
- Subject: Re: Why have a ChangeLog file if you already have commit messages?
- Date: Sun, 23 Sep 2007 21:06:32 -0500
On 9/19/07, Havoc Pennington <hp redhat com> wrote:
> 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
> "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
> 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.
In my experience the maintainers of a software project should have a
commit log policy and reject changesets that don't conform. Easier
said than done, I know. It is of course much easier inside a company
for product based software projects -where our maintainers review not
only the changes but also the changeset comments before pushing the
changes to our stable Mercurial repos from person ones.
> 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,
> 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.
> desktop-devel-list mailing list
> desktop-devel-list gnome org
] [Thread Prev