This post is very outdated and does not represent the standards or practices that I currently endorse or implement.

This post talks about an old, dead project, SprayFire; you can read about it's demise. All links pointing to the project have been removed.

As the development of SprayFire progresses I'm constantly evaluating what I'm doing, how I'm doing it and what tools I'm using. Lately I've been thinking about the way I use git, my version control software of choice. Looking through some of the commits for SprayFire I can tell that my commit strategy needs some work. Commit messages are sometimes lengthy or don't really convey what the commit is doing. What are some things that I can do to improve my commits and make for a more maintainable project?

commit, commit, commit

Well, the first thing is to simply commit more often. Too often I find myself making a series of small refactors and never commiting my changes between refactors. Next thing I know I've found myself making a single commit where the entire file has changed and instead I should have made three or four smaller commits changing a fragment of the file at a time.

While small, simple classes can make this easy to get away with it can bite you when your classes become more complex. It is important to establish a "muscle memory" if you will. What you do with your small, simple classes will wind up translating over into the bigger, complex classes. If you always commit early and often then you never wind up finding yourself refactoring an entire file between commits.

thou shalst format thy commits

Please, for all that is good and right in this world, have a consistent format for commit messages. While my own messages could certainly use some work in this regard one of the things I do adhere to is a 3 letter prefix on every commit that tells me what I'm doing. Here's a list of my prefixes and what they mean:

| Prefix                    |       Meaning                                     |
|   ADD                     | I have created a new file that did not previously |
|                           | exist in the repository.                          |
|   UPD                     | I have updated a file that already exists in the  |
|                           | repository.                                       |
|   DEL                     | I have removed a file from the repository.        |
|   DEL & ADD               | I have renamed or moved a file                    |

This makes it easy to look through commits and tell at a glance what I've done. It also makes looking for commits with git log extremely easy. Wanna know about any deleted files? As simple as:

git log --grep=DEL

Although I have a prefix strategy after that it has been pretty much free-for-all. Perhaps instead I should have a concrete format for commits. Maybe something that looks like:

prefix class_or_file message [issue link]

use github's resources

The wonderful thing about github is the simple, flexible, open-source tools they make available to you. This blog for example is powered by github's very own Jekyll. Not only that but they provide you with issue/milestone tracking and a simple wiki. Certainly for larger projects these tools may not be sufficient but for intermediate use these are wonderful tools to help manage your project.

Write an issue for everything you want to do.

Yea, that's right. If it is an important part of your application, and let's face it what isn't, or needs to be done write up an issue. Tag a label onto it, assign it to somebody. Assign it to a milestone, a concrete goal for what you want your application to do. The reasons to do this go beyond just making clean commits but helps guide you to a better application. You're much more likely to rewrite a flawed design typed up as an issue as compared to if you actually took the time to implement that flawed design. This has already saved me countless times with SprayFire. You also get the satisfaction of closing issues and seeing actual progress with your application.

But, I started to ramble. How does that impact our github commit messages? Well, remember those wonderful tools that github provides for you? Part of that is referencing issues and milestones from within commits. Does the commit you just made have an issue associated with it? At the end of the commit message add something that looks like: cspray/SprayFire#1, replacing your github username, repository name and issue number as appropriate. You automatically get a link to that issue in your commit and, even cooler, the commit shows up when you look at the issue! This can be an incredibly handy tool to easily get the documentation needed for a given issue or commit.

Even cooler, as detailed at the github blog, you can actually close issues with commit messages! Awesome! Just prefix your issue number or link with any of the below words:

  • fixes
  • fixed
  • fix
  • closes
  • closed
  • close

wrapping it up

Well, now that I've talked about making better git commits I think I'm gonna go make some of my own. Happy committing.