This is a part of Deployment Academy: Learn how to deploy bug-free webapps like a boss.

Version control: best practices

Jean-Philippe Boily, Wednesday May 28, 2014

Version control is something that every shipping team uses, but there’s not a lot of talking about the right way to do it. Used properly it can improve your code culture and help you move faster. Let’s dive into some best practices for Version Control and the workflow we use here at Rainforest.

This should be applicable for most Version control systems (VCS), but we’ll focus on Git and Github for this post since that’s what we use.

Commit early, commit often

Commit early and often. Don’t wait to be done with the whole feature but commit as soon as you have a chunk of code that works. You should definitely commit multiple times a day, and often many times per hour. If you find that you have broken something that was working, but cannot revert to the working version because you didn’t commit it… well you can guess where we’re going with that.

Write meaningful commit messages

Your commit messages are also really important. Try to keep them somewhat short and meaningful. Commit messages like “meh”, “fix”, “lol” and so on are useless. Your are writing to your future self and the other people working on the codebase. It’s important to be able to tell what a commit is all about from its message.

Good, descriptive commit messages

I like to share this sentence when talking about commit messages: “Write every commit message like the next person who reads it is an axe-wielding maniac who knows where you live”.

Branching policy

Never forget that branches are cheap in Git: they are easy and light, and you should use them all the time.

Our preferred branching model is very simple:

  1. We have a develop branch, which is the current state of our staging and QA environments. This is the branch from which we branch off.
  2. The master branch is the current state of production.
  3. When we want to work on something new or a bug fix, we simply branch off of develop in a new feature branch (a regular branch prefixed with feature/branch-name). We do the work and then create a pull request on GitHub to merge back to develop (we’ll talk more about this later).

(For a much more thorough overview of branches in Git, check out this post over at nvie.com)

Pull requests

What are they? Who better to explain than GitHub:

Pull requests let you tell others about changes you’ve pushed to a GitHub repository. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

This is incredibly helpful to see the changes someone made. This is a core feature of GitHub that we use extensively. It will let you not only see the changes but comment on them too enabling you to do code reviews.

Creating a pull request is very easy. Check out Github’s guide.

Code reviews

Why would you want to add code reviews to your flow? While you may feel like they slow you down, you’ll reap the rewards tenfold in the long term. They help catch bugs and weird things you might be doing. They also help keep code quality as high as possible and naturally push your team to develop a common coding style and set of best practices.

So what’s the best way to do code reviews?

First up: review your code yourself. Make sure you didn’t do something stupid that will make your co-workers spend time on bad code (this, much like rubber duck debugging is often enough to greatly improve code quality). Knowing that your work is going to be closely evaluated by a teammate that you respect is a real motivator to do things right and avoid sloppy mistakes.

The pull request for this very post!

We are lucky to have great and lightweight code review tools like pull requests on Github. Every pull request created is examined by at least one team member. We look for errors, confusing code code, antipatterns, etc. We add comments to everything we see. The idea is to ship better code and make us better programmers, so everyone is happy to have their code reviewed. A culture of frank, friendly criticism is incredibly important in minimizing technical debt.

Confusing code being called out in one of Rainforest’s PRs

Pull requests are also useful for remote teams because they make the deployment process asynchronous. I can submit a pull request for a major feature change, and the next morning I have a list of issues with the code to address before merging it.

It’s also great at getting everyone better. Reading other’s code is helping you to improve your coding skills on the long run too!

What about your version control practices and development flow?

Read more articles like this. Get a quick post in your inbox each week: