Do you use version control? If you’ve been in the software industry for any length of time, chances are good that you’ve aware of tools like Git, Subversion, CVS, or one of the many others.

Version control has many benefits, but the main benefit is one of safety. It’s the ultimate undo button for your application. Made a change that broke something? Look back in time to see what changed. Accidentally deleted some code you needed? Restore it from a previous version. Don’t like the way a refactoring turned out? Revert the commit. Need to know what Terms & Conditions were published on your website three years ago because you’ve been sued by a disgruntled customer? No problem, here’s what they said.

What Belongs in Version Control?

The question isn’t whether you should use version control. The question is what should you put in version control?

The answer? Everything.

You may have noticed that I’ve been using the term “version control” and not “source control”. This might seem like a subtle point, but the term “source control” suggests that only source code should be managed this way. “Version control”, on the other hand, implies a much broader scope.

Here are some of the things you should put in version control.

• Source code. This is anything required to compile and build the executable artifacts for your application.
• Configuration files. Any information that is injected into an application to allow it to run in a particular environment. Properties files, YAML, XML, etc. Anything that is ready by the application when it is running.
• Deployment scripts. Anything required to get the application installed and configured on a particular set of servers and ready to run. This might be in the form of Puppet jobs or simply a set of shell scripts that copy the application and configuration to the appropriate locations.
• Development scripts. Any useful tools you use to write software. Everything from scripts to create a new project, to code style configuration for your IDE.
• Documentation. User manuals, requirements documents, UX specifications, design drawings and documents.
• Operating System setup files. Anything required to get a server ready to accept your code. This is related to the deployment scripts, but typically is a separate thing. Your IT department may provide a standard server image, and then the deployment scripts convert it into the type of server you need.

Anything that is generated that is in any way, shape or form related to building software should be in version control. Have you ever passed around requirement documents or UX specifications via email? Are you sure you have the most recent revision? If they’re in some kind of version control, you’ll know.

There are some who even advocate checking in third-party dependency libraries into version control. I tend to think this is overkill, as long as you have a local repository of the external libraries you depend on. But the goal is the same. You should be able to recreate your application as it existed at any point in time. That, obviously, includes the libraries it depended on.

Many Forms of Version Control

Version control can take a lot of forms. Most of us are familiar with systems like Git, Subversion, CVS and the like. But take a system like Atlassian’s Confluence. Every page created in that system maintains the history of changes. If I want to see what changed in the most recent version of a document, I can go look at its history and do a comparison.

If you’ve used WordPress, you know that every post and page maintains a revision history.

Even a Docker container repository is a form of version control. There’s a history of what image derived from what.

As long as there is some way to examine the history and view previous versions of the artifacts, you have a version control system, even if it’s not named Git.

Best Practices

Given that we should use version control for everything, it makes sense to use it as effectively as possible. There are a few things that I consider best practices when working with version control systems:

• Provide meaningful commit messages. If someone is troubleshooting a problem, a commit message of “Fixed stuff” is of no help whatsoever. However, “Updated cache expiration policy for the xyz cache” gives you something to go on. A good commit message usually contains a summary followed by a more detailed description of the change.
• Keep branches short lived. Systems like Git make it extremely easy to create branches, allowing you to experiment. The problem is that the mainline doesn’t sit still. The longer your branch lives, the harder it becomes to merge back into the main, master branch. There are even some who advocate not branching at all. That is, all changes go straight to master.
• Delete, don’t comment. If you need to remove a line of code, remove it. Don’t just comment it out. If it turns out that you needed it after all, you can always get it back. After all, it’s in version control. Let the version control do what it’s good at and keep your code clean.
• Tag releases. Most systems have a way of logically marking a point in time with a label of some kind. Whenever you do a release, tag all your systems with the name of that release. That way, if you need to roll back or compare to the previous version, you have a marker to get back to.
• Store backups. Computers die, hard drives crash. Make sure that you have a copies of everything. Systems like Git make this very easy to do (just push to a remote branch). But whether you’re using a central system, like Subversion, or a distributed one, make sure you have lots of copies.

Conclusion

Version control is one of those things that may feel like a hassle at the time. But when you need it, you will be happy that you have it.

Keep in mind that version control doesn’t have to mean something like Git, it can take many forms. Once you’ve picked a system, use it as it was meant to be used.

If you remember nothing else from this article, remember this: whatever it is you’re writing, put it in version control. Even if you’re working on a personal project, put it in version control. You’ll be glad you did.