Source code management, or version/revision control, is one of the most useful tools that a developer has, especially if this person works with others on a shared code base. However, I've recently realized that some people don't understand what a good "commit"[1] entails. (I'm not naming them, or whether they come from my professional or hobby "spheres of influence".) It doesn't matter whether you're using Subversion, Bazaar, or even CVS. There are a few principles that you should consider when you make a "public" commit (as opposed to a "local" commit, which is supported by distributed version control systems):
- Limit your commit to one discrete idea. This can be fixing a bug or adding a new feature. Obviously, there is an exception when you happen to fix a bug by creating a new feature, but these instances tend to be rare. The big reason for this principle is that developers are (generally speaking) not infallible. If it turns out that the commit introduced bugs and/or regressions, it is easier to revert an entire revision (through whatever means your SCM provides), than to comb through the differences between the revisions in question for the "tainted" code.
- Good commit messages are key. Due to the way that most source code repository viewers work, it is considered good practice to summarize the commit in the first line, and then give a more detailed explanation in subsequent lines. This is actually similar to how writing is taught (at least in the US): provide a topic sentence in which you summarize what you're going to write about, and then write your content. In this case, though, you don't need a summary/closing statement at the end.
-
If your project management and/or your SCM software supports it, annotate your commit as much as possible. I'll give two examples as to what I mean:
- Bazaar lets you annotate your commit with a couple of metadata flags when you invoke bzr commit: --fixes=[BUG] and --author=[AUTHOR]. The flag --fixes lets you annotate which bug this revision is supposed to fix, and --author lets you specify the author of the code, e.g., if you are just committing a patch for someone else who doesn't have the proper permissions to do it themselves.
- There is a post-commit hook for Subversion, distributed with the Trac project management system, that allows tickets to be changed based on the existence of certain key phrases in a commit message. For example, the message
Add foo. Addresses #12345
adds a comment to ticket 12345 with that commit message and a link to the revision, whereas the messageAdd bar (fixes #12345).
performs the same task as the "addresses" phrase, plus it sets the ticket status to "closed". In my opinion, putting the "fixes" or "addresses" phrases at the end of the first line is preferable to putting them in the detailed explanation.
Hopefully, this is helpful to those who are new to using version control systems, and those people who are the "gatekeepers" of the repositories. Comments and criticisms are welcome.
1: The difference between a "commit" and a "revision", in my view, is that a revision is a patch that has been committed to a repository, whereas a commit is the process.
Posts
