Version Control

I’ve noticed a lot of people don’t really ‘get’ what version control is, or how it works. This is most evident when you watch the WP plugin repository.

Around 400 commits are made daily to the repository, which doesn’t seem like a lot until you compare it to core trac commits. Now WordPress Core never commits until they’re sure the version in trunk is functional (since many of us use trunk on live sites), something most devs don’t have to worry about unless they use trunk as ‘live’… Let’s not talk about that.

Instead of going into code today, I’m going to explain a little theory and talk about what version control is, why you want to use it, and how to use it.

If you’ve ever saved a document, had MS Word crash, and come back to be asked what version of the document you want to restore, then you actually already have an idea of what version control is. You’ve possibly just never had to do it yourself. Version control is a very simple concept: saving versions of a file so you can go back to the older ones. Sounds easy right? Yes and no. Most people are accustomed to a different way of saving.

Traditionally, we’re taught about saving as something you do regularly and often. After all, we’ve all lost that crucial document by forgetting to save. Apple has been changing this on us, having a much more robust auto-save process, and a better restore. It coaxes you into a place where you don’t think about saving anymore. There’s no save button on my iPad, and I actually use it to write a lot of the time. That freaks me out still, but so far it’s worked really well.

In contrast, I have my coding. I sit and write, save a lot, test a lot, and when I’ve got a change that works, I commit my code. You see, version control is like a second type of saving. One save is me working, and one save is me ready for someone else to test. But the best thing about version control is how it saves changes. You check in code, and SVN (or Git), and the server checks the changes and records what changed in a way that is easy to read. Here’s an example picked at random from the hundreds I skimmed today:

See how beautiful that is? Right away you can see what changed between versions! You, and anyone else who wants to troll a revision log, can see what you changed, which makes it easier for people to write a change log for you (if you happen to work that way).

Where I see the most people making mistakes with version control is missing out on the two rules you need to adhere to, if you want to use them effectively.

1. Never Delete Files
2. Trust The Tool

That’s it. That’s all you have to do. I see a lot of people correct files by deleting them and uploading new versions. This is flat out doing it wrong, but I can see why people think it’s what they should do. You have to trust your tool, and know that it will see the new file, tell the differences and record that. If you delete a file, it stops you from being able to compare it to earlier versions and that’s a problem. Bug tracking becomes much harder, as you no longer have a quick and easy way to see what changed. Sure you can compare two files, but you’ve now put up a barrier for the next guy who picks up your code. What if she doesn’t have that previous version? What if she has no way to get to it, and you were hit by a bus and are in a coma? Or not. But still, building barriers between yourself and the next person is lacking foresight. Worse, you build barriers for yourself.

It’s hard to trust the tool, and just as it took me months to get used to the iPad’s way of saving files, you have to get used to how version control saves things. This isn’t FTP where you’re always replacing a whole file, you’re making incremental changes. A check in is not a delete and replace (unless you’re using some of the horrific tools I’ve had the dubious pleasure of using in the past). Getting past that one hurdle will make your life much better with any tool you use.

As for never deleting, I come to this from working at a bank. We never deleted anything. Ever. Not once. You always keep all versions of your code, even the broken stuff, because legally you had to. But in the end, I feel that was a great practice to get into. Disk space is cheap and you won’t ‘run out’ of space any time soon. I keep a copy of every plugin’s latest version on my hard drive, and I’m not out of space.(I don’t have SVN checkouts, that would be a little much.) Also there’s no point to deleting your older code, since they’ll just show up in SVN anyway. It remembers everything you checked in. Ever.

Now, I cannot give you advice on the best way to tag or branch code, as each person comes up with their own methodology. I will say this: Don’t use ‘trunk’ as your stable releases on SVN. Git’s a little different, but I wouldn’t use it there either. Instead, use trunk as your playground. When you have a functional change, commit that minor change. When you have a major change and it’s ready to go, tag it and release it. In that way, your beta testers can safely use trunk, and your normal users never get hurt. By the way, making frequent commits may feel like a smart move, but you don’t need to. Check in a working copy. Oh and don’t go back and edit your tagged versions, unless it’s a very minor change. Someone is sure to have downloaded it, just tag a new version and go forward. As I always explained to people at the bank “You don’t go backwards with code, you go forward.”

I don’t expect this to be a perfect primer on how to use version control, nor was it meant to be, but I hope I demystified it a little. If you have great primers for people on SVN or GIT, aimed at first time users, please share them!

Ipstenu (Mika Epstein)

I’m Mika (aka Ipstenu) and I’m complicated. I’ve been on the net since the days of dedicated terminals and Novation CAT modems and solved Missionaries and Cannibals (or Goats and Cabbages) before I was six, and blog about WordPress and technical/computer things at Half Elf on Tech.

See Full Bio