What constitutes a valid SCM message?

Question

I’m currently writing some hooks for a new SVN instance and I’d like some feedback on what criteria people believe should be applied to verify the commit message is sufficient. This particular SVN instance will be used by a broad range of developers with varying knowledge of SCM best practices.

I’m trying to strike a good balance between forcing enough information to properly describe the change but not becoming overzealous and making life difficult on people who have succinct yet perfectly valid messages. The sort of thing I’m trying to reject is messages like “updated” or “added file” so limits on word count and message length are the obvious choices.

What other criteria would you use to reject messages which don’t properly describe the change? Please keep responses focussed on how you would qualify a satisfactory message; I’m acutely aware of the social need for education and this is happening in parallel.

BTW, don’t need to worry about references to work items or bugs in this particular case.

Answer 1

I honestly think that any specific criteria as a hard requirement is absolutely worthless. If you've ever seen a website which requires a minimum number of characters in a review/comment (dealextreme, and even this site come to mind) you will quickly realize that the effect just isn't what you want. Instead of people insuring that reviews and comments are longer, they'll just find more filler to make sure they hit the known and hardcoded minimums.

Ultimately the problem has to be dealt with as a social rather than a technical problem. Each instance of an inappropriately uninformative comment needs to be brought to the attention of the person doing it and explained to them.

This still won't solve the problem 100%, but its the closest approach to working that I've found.

Having said all of that, I'd be really surprised if someone can write consistently good cvs comments in fewer than about 40 characters. :)

Answer 2

This will probably not get you much. If you reject "updated", then people will just make something up that gets their commit in. "Added a new fizzleglorb to saldkj dot quux." Technical solutions to social problems don't work.

Also, maybe consider a tool like Git so that you can coalesce related commits. When you are in the middle of hacking, you don't want to write a detailed message. But when you are going back to review your work and compress it into a logical chunk, that's when you want to add the documentation about what you are doing.

Answer 3

I agree with the other answers. People unwilling to cooperate will always find a way around your rules.

However, what I always do is the following:

• set up a pre-commit hook to check that a comment is provided (i.e., commit message is not empty), just to prevent that people (myself included) 'accidently' forget to provide one. Don't bother with any checks on the content of the commit message though; it's a waste of time.
• put a pre-revprop-change hook in place to allow editing commit messages afterwards (this is not allowed by default)

Answer 4

I agree with other answers that validation at this point will not be 100% effective. But having some validation will help achieve partial compliance.

I therefore suggest the following:

• have a minimum number of character requirement. Determine an appropriate number based on surveys gathered.
• list down some possible unacceptable key phrases. Be careful not to include words that could both be acceptable and unacceptable like "update".
• emphasize rules when cascading SVN commit policy.
  Determine a very good medium to orient users.

I believe rules will minimize occurence of uncompliant users but not totally eliminate them.

Hope this helps.

Answer 5

I've found that requiring at least 15 characters (excluding whitespace) works reasonably well. Don't try to overdo it with more elaborate checks. Setting up a commit mailing list will also help; it advertises good examples and adds social control.

There will always be a few developers who take it as a challenge to minimize any useful information in their commit messages. But if I look at the SVN logs before (90% empty) and after (80% somewhat useful) the pre-commit hook was installed, I conclude that the situation has improved here.