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 <[EMAIL PROTECTED]> * src/file.c (some_func): Use g_list_reverse(). Good ChangeLog: 2007-08-18 Federico Mena Quintero <[EMAIL PROTECTED]> 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 _______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
