Tip o’the Day™ 2: Commit Often

I will assume that you’re using a revision control system of some kind. If you’re not, you really, really need to. Even if you’re the only person on the project, you need to use something. Whichever system you use, be it Subversion, Mercurial, CVS, Git, etc., there are a few subtle, but significant differences in how you use it that can have a tremendous impact on productivity. I’ll show you a few techniques on how to use your system more effectively.

Note 1: When I say ‘commit’, I intend that to mean the act of submitting the changes to the repository. I use the word commit because that’s what Subversion (the system I use) calls it. Some systems call it check-in.

Note 2: The article is geared toward teams. However, most of the principles still apply if you’re the only member of the team.

Note 3: The article says “code” a lot. This is because I am a programmer. For the purposes of this article, “code” means any project file: source code, graphics, data files; any asset related to the product.

The Traditional Mindset

Traditional source code management systems for teams employ a notion called “code ownership”. That usually means that each member of the team is assigned a code module (or modules) that only that person creates and maintains. The motivation behind this is to limit the number of conflicts that happen when it’s time for everyone to merge their changes.

This “merge event” becomes a big deal because it doesn’t happen all that often. In the days (or however long it was) since the last merge, everyone is accumulating changes and everyone’s code tree is getting more and more different than everyone else’s. The more the code trees differ, the bigger chance you have that you’ll have conflicts when you merge. The act of merging becomes a painful chore that everyone hates. When the team is busy fixing build problems, they’re not actively moving the product forward (by adding new code to the project).

Code Ownership

For other, more agile developers, the act of merging is virtually non-existent. How is this possible? The only real difference is how they interact with their repository. Sure, there are similarities: someone has to create a code module for example, but that’s where the similarity ends.

Agile teams commit constantly. I’m not talking about “whole hog” Continuous Integration (like automated builds, etc.), but integration at an individual level. Committing constantly normally means performing a commit at least once a day. This is a good rule of thumb to follow, but I like to do more than that.

My approach has two main steps: 1) before I make any changes I make sure I have the latest version of the repository, and 2) I commit after every task, no matter how small that task was or how long (or short) it took to complete.

By approaching the repository this way, the entire team is always working with the latest version. Effectively, their mindset is “we own this code”, instead of “I own this code”.

Step 1: Update

Before making any changes to the repository, do a full project update. Once that is done, do a full build. Only when the build has been made cleanly can you proceed to Step 2. If there are problems, you resolve them, even if you weren’t the cause.

Step 2: Complete Your Task

The next step is for you to do the work you set out to do. Fix a bug, start a new module, whatever. Once you have determined that your task is complete (your testing process was successful), you can then move to Step 3.

Step 3: Update Again

Step 3 is perhaps the most important: do another update. Someone could have committed changes while you were making yours, so if you do an update before you commit, you get their changes and are guaranteed to be working on the latest version. Any conflicts, build problems, test failures, etc. must be resolved immediately. Since (relatively) so little changed, it’s much less effort to fix any problems at this step.

Step 4: Commit Your Changes

The very last step in the process is when you submit your changes to the repository. Since you checked – and double-checked – that you modified the latest revision of the repository, you can feel pretty confident that everyone else won’t have a problem when they update. The only potential problem you might have is forgetting to add new files to the repository that you created. If you have a proper continuous integration system in place, you’ll know very soon if you forgot something.

When you commit, it’s important to always add a meaningful description of the changes. It might seem like a chore at first, but the time spent (and it’s not much) will pay for itself when you need to rollback your version for any reason. You want that history present so you know where to start looking for the appropriate revision. If the messages are blank or lack any meaning, you’re doing a binary search which is tedious and wastes your time. Having descriptive messages gives you laser-sharp focus.

The Repository Is The Master Version

I want to end with a note about the repository. You have to treat the repository as final, releasable code (files, assets, etc.) That is to say, when you commit something to the repository, you are effectively telling your product (and your team) that you are considering the affected files as being releasable. In other words, if the product was to ship tomorrow, you have made an unwritten agreement with your teammates that you have tested the change to the best of your ability and that it is worthy to be included in the product that the consumers will use. If you can’t make that level of commitment, you should not incorporate it into the repository.

In other words, do not treat your repository as a temporary space. It’s very easy to create a ‘temp folder’ and ‘just add it there quick’ and use it as a shuttle for your teammates (or yourself as a backup). You must resist the urge to do this. Over time, they will accumulate and clutter up your repository.

It also goes without saying that you should not submit changes to the repository ‘just to commit at least once a day’. If it’s not finished, don’t submit it. It might seem to some that I’m contradicting myself by going against the guideline of submitting small changes. I’m not. The guideline is just that, a guideline, and not a hard-and-fast rule that must be adhered to above all else. Sometimes there are tasks that end up being larger than originally planned. It’s OK to take longer than a day to submit something. However, don’t make it become a habit. Those occasions should happen only rarely.

Note: What I mean by all of this is that make sure you commit releasable code to your main branch. It’s totally fine to make branches and commit to those as often as you need to.

Tip o’the Day™ 2: Commit Often