Best practices for version control comments

Question

There is a lot of conversation about commenting code, but how about commenting on check-ins?

I found this blog post: http://redbitbluebit.com/subversion-check-in-comment-great-practices/

As the guy who is putting together the release notes, I am looking for ways to make that job easier.

Currently we defined our own scheme with <Begin_Doc>...<End_Doc> for anything that should be published to our software customers. But even for the internal stuff, I'd like to know the "why" for every change.

Answer 1

Every feature has a ticket/issue/bugreport/task/whatever-you-call-it, and the ticket number is always referenced in the check-in comment. This gives context.

Answer 2

I would advocate NOT using/overloading your version control system for this. I would suggest the issue tracking software as a better fit.

For one, it does not seem appropriate to have developers add all the context and duplicated information in a commit message that is already in a requirements doc or issue/defect system.

You can use a tool to gather the relevant fixes/issue numbers that are in the commit comments and then go collect those from your other repository, but I think it is a mistake to basically make your revision tool an external facing thing.

You need to define what the Source/version repository/SVN is - is it for managing your source files, or is it also for writing release note. I think it should not be overloaded.