Version control: a practical guide

The version of this that works is simpler than the version most people imagine. This guide covers what version control actually involves, where it usually goes wrong, and how to tell whether yours is in reasonable shape.

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Nothing below assumes a large team or a large budget — most of it is a decision somebody has to make and then write down.

Why this earns attention

Small commits with clear messages are a gift to future you. The reasoning matters more than the rule, because the rule has exceptions. It is the sort of thing that looks like polish right up until it costs you an enquiry.

For most businesses the question is not whether this matters but how much of it is worth doing right now. That depends on what you are trying to achieve in the next few months, not on best practice in the abstract. There is a version of this that is over-engineered, and it is worth avoiding.

How we handle it

Branch naming conventions cost nothing and prevent confusion. There is a version of this that is over-engineered, and it is worth avoiding. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.

The question is rarely whether something can be built, but what it costs to keep running afterwards. The version that works in practice is usually less elaborate than the version described in the guides.

If it is not in version control, it does not exist. The cost of getting this wrong is rarely visible on the day it happens. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

A working checklist

If you want a quick read on where you stand, work through this. Anything you cannot answer confidently is where to start.

• Small commits with clear messages are a gift to future you
• Branch naming conventions cost nothing and prevent confusion
• If it is not in version control, it does not exist
• Someone is named as the owner, not just assumed to be
• There is a date in the calendar to review it again
• The decision and the reasoning behind it are written down somewhere findable
• You could explain the current setup to a new hire in five minutes

Warning signs

The most common failure is not doing this badly. It is doing it once, during a launch, and never revisiting it. Circumstances move, the setup does not, and the gap widens quietly until something breaks or somebody notices the numbers.

• It was configured during a launch and has not been touched since
• Different people in the business believe different things are true about it
• There is no way to tell whether the last change helped or hurt
• The only person who understands it has left, or is about to

Most development decisions are really maintenance decisions wearing a different hat. This is the sort of thing that compounds, quietly, in both directions.

How we approach it

On our projects this gets handled during the build rather than added afterwards, because retrofitting it costs several times more than including it. We write down what was decided and why, so the next person to touch it is not guessing.

If you are working with someone else, the questions worth asking are simple: who owns this, how will we know it is working, and what happens when it needs to change?

Where to go from here

Pick the single item from the checklist above that would cause the most trouble if it turned out to be wrong. Fix that one, confirm it worked, then move on. Pick the one that would hurt most if it failed, and start there.