Question

I’m curious what kind of content should be in a versioned file commit comment. Should it describe generally what changed (e.g. “The widget screen was changed to display only active widgets”) or should it be more specific (e.g. “A new condition was added to the where clause of the fetchWidget query to retrieve only active widgets by default”)

How atomic should a single commit be? Just the file containing the updated query in a single commit (e.g. “Updated the widget screen to display only active widgets by default”), or should that and several other changes + interface changes to a screen share the same commit with a more general description like (“Updated the widget screen: A) display only active widgets by default B) added button to toggle showing inactive widgets”)

I see subversion commit comments being used very differently and was wondering what others have had success with. Some comments are as brief as “updated files”, while others are many paragraphs long, and others are formatted in a way that they can be queried and associated with some external system such as JIRA.

I used to be extremely descriptive of the reason for the change as well as the specific technical changes. Lately I’ve been scaling back and just giving a general “This is what I changed on this page” kind of comment.

Answer 1

Some guidelines:

• don’t write stuff that the VC system already tracks automatically: which files, how many lines, when, who did the change…
• do write what the purpose of the change was: “add UTF-8 support to ID3 tags”
• if you find that the purpose is unclear or multiple, you are probably better off doing several commits instead. Linus Torvalds can get away with writing “various fixes all over the place”; the rest of us shouldn’t take him as an example.
• if you have any sort of tracking system that assigns unique identifiers to issues or feature requests, by all means tag the comment with that identifier.