Change and other sorts of Logs

There has been a back and forth on formal ChangeLogs vs vcs commit messages via the GNOME mailing lists. Doing the latter exclusively has never sat well with me because I think it weakens good development practices (at least mine). I find many vcs commit messages lack the detail of ChangeLog commits generated by a workflow involving C-x-4-a in emacs for instance, which makes in easier to document changes on a per function basis, and that makes it easier for others to understand the changes that were made. And documenting on a per function basis forces me to review my patch prior to commit (good practice anyhow, but this puts it in my workflow).

This entry was posted in Free Software. Bookmark the permalink.

4 Responses to Change and other sorts of Logs

  1. jmmv says:

    The problem with most ChangeLogs is that they *only* document technical aspects and it is extremely difficult to understand the *reasons* behind a given change when you later examine them. When I read a project’s history, I want to know what changed and why, not how; the how can already be seen in the diffs. (OK, explaining some of the how is also appropriate in many circumstances but it shouldn’t be the only thing explained.)

    You’d also stick ChangeLog-formatted messages in your vcs commits and later extract a real ChangeLog for your distfiles. This is the approach used lately in monotone. And we have been discussing this exact topic on the past days; see http://lists.gnu.org/archive/html/monotone-devel/2007-09/msg00130.html for more details 🙂

  2. You know you are supposed to sent your time on coding, not on source code management?

  3. Mark Brown says:

    I think that’s a problem that a lot of DVCS people would rather solve via fine grained commits – of course, that’s not a 100% drop in replacement but the idea is that by having small, closely related changes you keep the detail level of the revision control history up. IME it’s a useful compromise and it avoids the merge problems that a text changelog is obviously going to have.

  4. Mark: the problem is that you cannot publish patches in Bugzilla that represent more than 1 commit, AFAIK.

    I like the comment bringing up the /why/ thing. I think there should be a rule in the server to check when pushing changes to whine if there was no “why:” string.

    Normally you would just put the bugzilla URL of the bug in the why field, though.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s