[fink-core] ChangeLog vs. NEWS files and git commit messages

[Max H. <ma...@qu...>]

Hi there,

I brought up the thought of getting rid of the ChangeLog files as we move to git, and I'd like to renew this, with some more explanations as to why.

What is the purpose of the ChangeLog files? To tell people what has changed, when and by whom. But for whom is this information meant?

Are ChangeLog files good for users?
===================================
For users it is of course interesting to know what changed in a given version of, say, "fink" (the package manager). But I'd argue that the ChangeLog files are not the way they want to see this information. The information is far too low-level and overly redundant. For users, a concise summary of the important additions, fixes and other changes would be far more useful. I.e.: A NEWS file. With entries like this:

0.32.0 (2011-10-27)
  - added support for xcode 4.2
  - replaced ChangeLog files by a single NEWS file summarizing what changed in each version
  - fixed a bug in the quantum flux compensator that could lead to accidental black holes in your basement

For reference, this is how I could imagine the file to look like: <https://github.com/scummvm/scummvm/blob/master/NEWS>. 

Are ChangeLog files good for developers?
========================================
For developers, the ChangeLog information duplicates a lot of what the VCS (git in our case) is doing: Tracking of who changed what when. Using "git blame" resp. "git annotate", and the corresponding functionality of github (e.g. <https://github.com/fink/fink/blame/master/fink-dpkg-status-cleanup.in>) it is very easy to figure out who changed which line when. The ChangeLog helps you not at all.

And what changed in each commit should be recorded *by the commit message*. As such, the ChangeLog should contain information that is equivalent to (or rather, a subset of) the information presented by "git log". Except that "git log" (and the various graphical frontends for it, provided by the github website but also native os x apps) provides far more capabilities. You can restrict by author, date ranges, affected files, etc.

Also, at least in "fink", the fact that we 25 ChangeLog files scattered around doesn't really help. Oh, and ChangeLog files can "lie"; e.g. it is easy to forget to update them when making changes.


Conclusion
==========
For users, ChangeLog files are inferior to NEWS files. For developers, ChangeLog files are inferior to "git log" and "git blame" and GUI frontends for those. Indeed, a ChangeLog file can be reproduced using these tools.

So here is what I propose:

Step 1:
Wwe should add a NEWS file, perhaps initially based on the content of <http://wiki.finkproject.org/index.php/Fink:Roadmap:New_Features> (and I'd then argue that this Wiki page and its subpages are redundant and should be removed). This information is a bit skinny and incomplete. I'd try to augment it by scanning through our ChangeLog files and repository history for a bit. 

For base-files we should do the same.

Once we have sufficiently good NEWS files (with as much historical information added as we care for), we can remove the ChangeLog files (remember that they are still there in case we ever want to look at them again).


Step 2:
To make sure that "git log" *really* has the same information as the ChangeLog file, everybody should strive to always use meaningful commit message. This is nothing new, though; this always should have been how you write your commit messages ;). But for many reasons it makes sense to make it a bit more precise to state what this means. So many projects these days chose to adopt some kind of "commit message guidelines". 

For git projects, it has become typical that a commit should consist of one initial line <= 77 chars which briefly summarizes the changes. Then an empty line follows, and then (optionally) a more detailed description of the changes. Indeed, I'd propose to follow this guide <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html> or a variation of it.

For ScummVM, we took that guide and modified/extended it a bit, see here: <http://wiki.scummvm.org/index.php/Commit_Guidelines>. This also contains some examples for bad commit messages, and why they are better, and how to do it better.



Bye,
Max