views:

2617

answers:

9

I'm at the beginning of a new project, and I'm trying to set up the repository in a smart fashion and establish some code style guidelines for everyone to be able to concentrate on code.

Most of it is done, but I'm still unsure about the format I should enforce for commit messages. I'm all for freedom and just telling people to make them clear and thorough, but I've that it rarely works, people having very different notions of "clear" :).

And so far, I've never found a satisfying scheme. What I most often do is: a one line summary of the commit, then bullet points describing each change in more detail.

But often it's kind of hard to decide what deserves a bullet point and what doesn't, and some sort of classification, by features, file, or minor/major changes would seem appropriate. Sadly each time I try to do that, I end up writing stupidly long commit messages for trivial changes...

How do you do it?

+2  A: 
  • Bug ID: (If applicable)
  • Change Description:
  • Code Reviewed by:
  • Unit Tested:
  • Target Release Label:
Prakash
+1  A: 

We don't really care about the free text, but everyone is required to enter the bugtracking ticket id of the task the commit belongs to and who peer reviewed his code.

The first one may generate a little overhead for quick fixes but it can be a life saver. Having the actual reason of every single line of code handy is very valuable.

The second one just encourages to do peer reviews.

Maximilian
+4  A: 

I'm trying to follow these rules:

  1. Be concise
  2. Describe why you do, not what you do

Usual format for my commit messages is:

Issue: #[issue number] [short description]

If you have some kind of bug tracking system, provide issue number in commit message.
I found that many developers just write something like "Added X. Removed Y" but I can find this info looking at the code diff. If there is no issue number attached it can be hard to know why developer made some change.

aku
A: 

I find it rather hard to get commit messages right. Why not propose this:

Each commit message must start with the Bug/Task ID that is resolved by the commit. Anything else is just chatter...

Daren Thomas
Because we memorize what every bug in the tracker is, amirite?
Xiong Chiamiov
No, because the tracker can be consulted whenever you really need to find out. Also, this emphasises keeping commit granularity at bug/task level.
Daren Thomas
+1  A: 

One ting I always do, is if the changed is triggered by some sort of bug/tracker-software is to include the bugid in a consistent way. That way it is easer to track all changes related to a bug at a later stage.

Example:

BugID: 2345 Added validation of user input to avoid exploit.

Espo
+1  A: 

I think bug id (if there is one) is a good idea.

One of my favorite features about FogBugz is that you can set up a hook script so that, when you enter the bug id in the commit log, the commit information gets added to the FogBugz case.

Image from here


Beyond that, just write something meaningful about why you made the changes you made.

Mark Biek
N.B. tracking issue ids in commit messages feature is not specific to FogBugz, actually I think every other issue tracking system also supports this
dolzenko
+14  A: 

I think you have to rely on people actually being able to think for themselves. You can provide some basic guidelines, like the ones you outlined, but in the end people must understand them in order to follow them.

Here's an extract from my recommended best practices for version control:

Always write a comment when committing something to the repository. Your comment should be brief and to the point, describing what was changed and possibly why. If you made several changes, write one line or sentence about each part. If you find yourself writing a very long list of changes, consider splitting your commit into smaller parts, as described earlier. Prefixing your comments with identifiers like Fix or Add is a good way of indicating what type of change you did. It also makes it easier to filter the content later, either visually, by a human reader, or automatically, by a program.

If you fixed a specific bug or implemented a specific change request, I also recommend to reference the bug or issue number in the commit message. Some tools may process this information and generate a link to the corresponding page in a bug tracking system or automatically update the issue based on the commit.

Here are some examples of good commit messages:

Changed paragraph separation from indentation to vertical space.
    ...
    Fix: Extra image removed.
    Fix: CSS patched to give better results when embedded in javadoc.
    Add: A javadoc {@link} tag in the lyx, just to show it's possible.
    ...
    - Moved third party projects to ext folder.
    - Added lib folder for binary library files.
    ...
    Fix: Fixed bug #1938.
    Add: Implemented change request #39381.

In my experience, you have to follow up on people and give them directions whenever they don't follow the commit rules. You could of course implement a script to enforce some of the rules (like the prefixing and bug referencing), but that will not catch the lazy people who don't bother to write anything meaningful. I think it's important to explain why you want these conventions and how they will benefit the development team.

Setting up a commit e-mail list and monitor it for message is a good way to keep track of what people are doing. Whenever someone is committing something without a satisfactory message, you will know so and can tell them. I guess is the same way as with coding conventions, for them to be successful, somebody has to follow up on them.

Anders Sandvig
+1  A: 

We use Altassian JIRA as a bug tracker, and Subversion for our source control -- JIRA has a nice feature wherein it can track the commits related to that bug, and put it in the bug resolution history.

As such, the format we usually take is:

PROJECTCODE - 1234 : Reasonably detailed description of changes made

By "reasonably detailed" what I mean is that you don't just put "fixed bug" or "changed implementation", you usually put in a description that is not very specific bug still tells what was actually done, e.g., "Sorting strategy for SortingMethod() was changed from bubble sort to quicksort to improve performance".

Jon Limjap
+7  A: 

Some rules I try to follow:

  • First line of the description is a short summary of the change. Many source control systems let you see a list of changes that show this line, so it gives you a rough summary.
  • Include bug ID and bug title. Don't make people look it up!
    • Make the Bug ID be a URL to open the bug, if your bug tracking supports it.
  • Say what you changed.
  • Say why you made this change, instead of taking some other approach.
  • Be very detailed.
  • Making each change small makes it easier to follow the history + easier to write & read a good commit description.
  • When a change is strictly a refactoring, I start the first line with "REFACTORING:". This lets me ignore that change when looking for a deliberate functional change. (Of course, accidental functional changes, aka bugs, can still be in these.)

For an example of a highly-detailed commit message, see this blog post from my old friend Cyrus: http://blogs.msdn.com/cyrusn/archive/2005/03/27/402729.aspx

Jay Bazuzi