Was trying to come up with some style guide for commit messages in revision control systems (Subversion, Git, Mercurial, etc.) as very commonly it is a place where people tend to use poor or poorly-managed writing styles when they are in a hurry, or not. The contrast between the sophistication of engineering of automatic revision control systems and the lousiness of majority of commit messages I've seen is ironic, at least to me. Imagine a situation where one wants to data mine the commit message history in a revision control repository and do text analytics with it to find out some interesting thing about the project, it can be very useful for the commit messages to have a uniform format and hence more machine processable.

Some general rule for revisions and commits

• try to make a commit self-contained, i.e. logically-closely-related revisions should be committed together in one commit rather than in multiple separate commits
• try to make logically-unrelated revisions in their own separate commits rather than make a big revision including many changes that are logically independent to each other

Some general rules for having uniform format of the commit messages

• Use a short summary sentence at the top to summarize the main purpose/content of the revision. As both Git and Mercurial use the first sentence ending with period (.) for various purposes. If there are itemized details in the following, use ellipsis (...) instead.

• Leave a blank line below the summary sentence.

• Keep the lines shorter than 72 characters as that produces better line wrapping behavior for hg log and git log.

• If necessary, use bullet items below the blank line to describe details. Use different bullet for different types of revisions

  • + added new content

  • - removed existing content

  • % modified existing content and/or behavior

  • ! fixed bugs and errors

  • ~ tweaked content by making small and/or insubstantial changes

  • * misc and/or other unclassified changes

  • > to-do for future

• Try to use expressions with simple past tense or noun phrases.

Example commit message to a revision control repository:

Changed the logic dealing with magic input.

+ added an awesome new functionality
- removed obsolete content
% modified some existing code
! fixed a bad bug
~ tweaked some content
* some misc unclassified changes
> make the logic more robust