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

[Federico Mena Quintero <federico ximian com>]

On Sun, 2007-09-16 at 00:13 +0200, Jaap Haitsma wrote:

> 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.

We use ChangeLogs because we decided to do so when GNOME started:
http://developer.gnome.org/doc/guides/programming-guidelines/modify.html#DOCUMENT

Which brings me to the topic of

	CODE ARCHAEOLOGY

which is a hard-to-describe mixture of the following:

* Figuring out who wrote a certain bit of code.

* Figuring out why that person did that.

* Figuring out which are the relevant bug reports, if any.

* Figuring out the corresponding posts in mailing lists.

Say you find a bug.  You go find the code that causes the bug.  The fix
looks trivial, so you make it.  Now nothing works.  After scratching
your head for a bit, you get to understand that the code doesn't really
let you see all the assumptions that it has, and you need more context:
the "obvious fix" is completely wrong because of the interactions with
the rest of the code.

And that's where code archaeology begins.  If you have never had to do
it, you will not understand the value of a good ChangeLog.  It's the
sort of thing you understand with experience.

A ChangeLog that describes *what* changed is useless.  I could get the
same information by reading a diff.  On the other hand, a ChangeLog that
describes *why* a change was made is VERY useful.

Bad ChangeLog:

    2007-08-18  Federico Mena Quintero  <federico ximian com>

            * src/file.c (some_func): Use g_list_reverse().

Good ChangeLog:

    2007-08-18  Federico Mena Quintero  <federico ximian com>

           Fix for http://bugzilla.gnome.org/show_bug.cgi?id=12345 -
           the list of change notifications was stored in the
           wrong order, causing the re-play step to fail completely.

           * src/file.c (some_func): Reverse the list of change
           notifications before returning it.

The first example tells me *what* happened, but it's exactly the same
information that I would have gotten from a diff.  It doesn't answer the
question of "why do you need to reverse the linked list?".

The second example provides very useful info:

* It points me to a bug.  I can then look at the bug to see the whole
debug process and line of reasoning that ended in that fix.

* It tells my *why* the change was made, from the perception of the user
("... causing the re-play step to fail completely").

* It lets me avoid reading the diff ("... reverse the list..."), because
reading code is harder than writing it [1].

Basically, a ChangeLog should be a tool for you to figure out the
chain-of-causality that led someone to think it was a good idea to
change some code in a certain way.  This can get very complicated with
code that changes very frequently or code that is very delicate to
change.

As Havoc said, simply using commit messages tends to degenerate very
quickly.  It's terrible to see messages commit messages that consist
solely of "quick fix" or "fix a bug", when they in fact touch several
files.  People are lazy by default, and the lure of

   svn commit -m "quick fix"

is just too big (replace svn with your favorite tool; it happens for all
of them).

Writing a ChangeLog is a *complete pain in the ass* if you do it right
before you commit.  It's like cleaning your bathroom's faucet every
year: it's so gunky that you give up.  You have to do it frequently so
that the gunk doesn't build up.  In ChangeLog terms, this means
religiously hitting "C-x 4 a" in Emacs (or whatever your editor uses)
every time you modify a function or bit of code.  That way it's not
painful at all, and it even gives you a short history of what you've
done so far should you need to back up in your thoughts while writing
the code:  if you ever thought, "hmm, why did I do this?", that's where
a good ChangeLog would have helped you.  This helps when you've been
writing or modifying code for hours but you haven't yet reached a point
where you can commit.

Also, as a tool to correlate changes/bugs/etc., I prefer it if Bugzilla
entries have a copy of the corresponding ChangeLog entry.  That way if
you look at a bug in Bugzilla, you can see what to grep for in the
corresponding ChangeLog to go on exploring the code's history.

[1] http://www.joelonsoftware.com/articles/fog0000000069.html

  Federico