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).

3 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.