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

["Sean Kelley" <svk sweng gmail com>]

Hi,

On 9/19/07, Havoc Pennington <hp redhat com> wrote:
> 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.
>


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.

Sean


> 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
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/desktop-devel-list