If you have ever examined the source distribution of an open source project, you'll probably have noticed a ChangeLog file. This file lists, in good detail, all changes done to the source code in reverse order, giving their description, the name of the affected files and the name of the author who did the change. So far, so good. But I really think that these files, or better said, the way they are written and managed, is flawed. Let's see why:

ChangeLogs are written and controlled by hand. That is: you do a set of changes to the project and then proceed to write an entry that lists the files you modified and why you did so. Some tools, like GNU Emacs, provide hooks to simplify their writing, but, in the end, it is the software developer who ends up taking care of them manually. This is not really a problem when the project does not use a version control system (VCS, for short) to store its source code, because in this case, there is no other way to keep track of the changes.

But when you add a decent VCS to the mix (one that has, at the very least, changesets), such as Subversion or Monotone, things get much worse. Worse because the information you have in the ChangeLog is duplicated: once in the file and once in the revision history stored in the VCS. Not to mention that the latter is much more accurate than the former and is automatically managed by the system; e.g., you only need to write the purpose of your changes and it will associate it to the files you changed.

However, all has to be said: ChangeLogs are useful, but in the context of distribution files. E.g., when a user downloads a tar.gz file, he will want the list of changes to be included in it, because he may not be able to (or not want to) use an specific VCS to read it.

What I'm trying to emphasize here is that maintaining a ChangeLog by hand when you use a VCS system is not a good idea, and something you shouldn't need to do. Ideally, you'd generate it from the revision history in the VCS (AFAIK, Subversion can do it). E.g., before publishing a new release, you'd ask the VCS to build a ChangeLog based on the changes from version 0.1 and 0.2, stick it into your distribution file and release it. Your users could be happy and you didn't have to maintain it manually. Things get more complex when you have branches in between, but the VCS should be clever enough to generate a ChangeLog that details what happened to the source code; doing it by hand in this case can be painful.

Now, to the rants. I guess ChangeLogs were originated when there weren't (free) VCS systems available, because authors needed to document the changes between versions of their software. Then, when CVS appeared, things didn't get better because of its lack of changesets. That is, when a change is committed to the repository, its history is spread over all affected files, so you have no way to know which files were modified in a single commit — unless you take note of it in the ChangeLog.

I believe it is time to start throwing away ChangeLogs (in the traditional concept) at the same time you abandon CVS, by generating them in an automated fashion when publishing new releases. Development will be easier because you'll have something less to care about. But, of course, this is just my personal opinion.

Subscribe via RSS · Go to posts index

   Delivered by FeedBurner

Comments from the original Blogger-hosted post: