[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [flame] NEWS file is useless

From: Nicola Pero
Subject: Re: [flame] NEWS file is useless
Date: Thu, 26 Nov 2009 10:50:49 +0000

ChangeLog has less information, in a less useful format, than the svn logs and is a hold-over from CVS not storing repository-wide change information sensibly. With svn log, you can get a log of change messages at any granularity that you like.

I agree there is an overlap, but there are also some differences. ;-)

Subversion records a single log message for an entire transaction, which might contain changes to a number of files. A ChangeLog entry is supposed to contain a separate log message for every file that was changed.

You realise that svn lets you commit changes to different files separately, right? If you have independent out-of-tree changes, commit them separately (see r29053 to r29055; three commits, all created together but committed separately to provide different log messages).

I agree with your later point that you could simply write a ChangeLog entry in the subversion log - that way you still use subversion
transactions properly, but document the changes to all files. :-)

I don't think committing files separately makes sense instead - because you lose all the benefits of subversion transactions. If you get interrupted or lose network access between committing the separate files, the repository will be left in a broken state. That is bad.

Also, I do like having in the logs the information that the changes are part of the same transaction. You do a single diff and see all the
related changes to the different files, which is great. :-)

So I guess the solution to that would be instead to require ChangeLog entries to be committed to svn log.

Finally, the obvious advantage of a ChangeLog is that every source code distribution/tarball will include it. Subversion logs are only
available if you use subversion.

Subversion is available to anyone with access to the svn repository.

Yes, but in practice it is a pain for people who are not following the project. When I install software from third-parties, I hate when they don't include a properly detailed ChangeLog - eg, if I need to check if a certain bug in a certain file was fixed between version 1.7.4 and 1.7.5, I just want to download the 1.7.5 tarball and check the ChangeLog. I don't want to have to set up whatever versioning system they use just to check a single file - it takes time because every project uses a different one, etc.

I also occasionally work on gnustep-make offline, and the subversion logs are not available offline, while ChangeLogs are.

People can track it by subscribing to the RSS feed from, they can see an individual committer's changes by looking at the timeline on

Sure, that is certainly good.

If someone wants to do 'svn log > ChangeLog' when creating the tarballs, they can; just add it to the script you use to generate the tarball. Given that most tarball downloads are likely to be from people who just want to build the code, however, it seems like a waste of space.

It's definitely not a waste of space. ;-)

But if we were to agree that people would write ChangeLog entries in the subversion logs, then we could generate the ChangeLog from the subversion logs before release. Even if in practice that can be hard, since all the interesting information for existing projects is currently in ChangeLogs, so we'd need to prepend to these ChangeLogs the latest ChangeLog entries from the subversion logs, but the system would need to be able to figure out which logs to prepend and which to ignore.

Maybe a commit hook that copies the subversion log to the ChangeLog file makes more sense then, so the ChangeLog would automatically be updated whenever you commit.

If we want to go through this route, that would be ideal I guess.

So maybe we could adopt a different approach depending on the project. I certainly think ChangeLogs are very good for the core

I still haven't seen a convincing argument for it. Any of the information that people write in the ChangeLog file they could also write in the commit log. It is impossible to make a commit without writing a log message, it is easy to make a commit without editing the ChangeLog (you could add a pre-commit hook that prevented this, but no one has done so).

You're right that writing a subversion commit message is enforced, while writing a ChangeLog entry is not.

But on the other hand, ChangeLog entries must be in a certain format that require you to write a description of each change to each file, while subversion log messages enforce no format and people tend to write extremely short, unexpressive messages such as "fixed bug" or "improved performance" when they maybe have changed hundreds of lines in lots of different files. When you're later trying to debug some failures caused by an old change, you need some information on what they were trying to achieve, or why things were changed -
a more serious and detailed description of the changes.

So if we agree to move to subversion logs, we still need to somehow enforce people to write detailed ChangeLog entries (it's fine to have them
committed to the subversion logs) of what they did to each file.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]