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

[Behdad Esfahbod <behdad behdad org>]

On Sun, 2007-09-16 at 21:43 +0200, Thomas Vander Stichele wrote:
> On Sun, 2007-09-16 at 00:13 +0200, Jaap Haitsma wrote:
> > Hi
> > 
> > Talking to Daniel "Cheese" Siegel we asked ourselves:
> > Why do all GNOME projects have a ChangeLog file?
> > Isn't it redundant when you just save a commit message.
> 
> Because they communicate at different levels.

Well, with the rule that all commits should have accompanying ChangeLog
entries, there can't be much different levels of communication.

> I have yet to see a project that has clear, concise commit messages, and
> all the commits are well-defined, atomic, and no screwups.

See cairo.

> The number of commit messages that go "fixed stupid typo" or "I was
> drunk when I commited this" make a commit message log unsuitable as a
> candidate for a ChangeLog.
> 
> When I'm reading a ChangeLog, I want to know what changed in the
> software overall; what changes the developers are making, and why they
> are making them.  I don't want to read about every single small detail
> they changed while making those changes.
> 
> When I'm reading a commit log, I typically figure out what the hell a
> developer was thinking when he introduced a bug or did something silly.

Not sure I follow.  IMO many projects have crappy log messages because
people already wrote the important stuff in the ChangeLog, so they think
that the log message is not important.  If you tell them that commit log
is where the ChangeLog comes from, that changes everything.  Of course
the downside is that you can't use prepare-ChangeLog.pl, but if you are
committing atomic changes with git, it doesn't matter as your changes
apply to all files involved.  No need to go into per-file detail.

This is cairo's commit log for some recent commits for example:

commit 21ab44f11d3d20eead5d988c7a6cf48eebff08c7
Author: Behdad Esfahbod <behdad behdad org>
Date:   Mon Sep 17 16:41:52 2007 -0400

    [ChangeLog.mk] Make make rule depend on .git/HEAD, not .git
    That is exactly what we want.  Kristian H�rg suggested it.

commit 3f4875dbe20e1d093d70f49c32f7ddf6a6e6ef61
Author: Adrian Johnson <ajohnson redneon com>
Date:   Sun Sep 16 20:26:33 2007 +0930

    Analysis-surface: Use pattern extents to limit show_glyphs extents

commit 14786385b40aa0ae83e3b077a82e3f34aba63f22
Author: Adrian Johnson <ajohnson redneon com>
Date:   Sun Sep 16 19:43:28 2007 +0930

    Change paginated surface size when PS/PDF _set_size() called
    
    The finer-grained fallbacks would not work correctly if the page
    was set to a larger size.
    
    Add _cairo_paginated_surface_set_size() function that is called
    from cairo_ps_surface_set_size() and cairo_pdf_surface_set_size().

commit 46cb7e69526e8b5663077e7409dc232a0f56800b
Author: Adrian Johnson <ajohnson redneon com>
Date:   Sun Sep 16 16:32:54 2007 +0930

    PS: Remove initclip operator
    
    The DSC and EPS specifications do not allow the use of initclip.
    Instead each page is wrapped in a gsave/restore pair and a
    "grestore gsave" is emitted when the clip path is reset.



> Just my 2 cents,
> Thomas
> 
> 
-- 
behdad
http://behdad.org/

"Those who would give up Essential Liberty to purchase a little
 Temporary Safety, deserve neither Liberty nor Safety."
        -- Benjamin Franklin, 1759