Version Control

Overview

In today’s world, project development is always backed by a version control system (VCS) .

In this guide, we cover the approaches we recommend to be used with GitHub as the VCS of choice, as it is, from our experience, the most used system out there.

GitHub Flow

When working with GitHub, there are a couple of different workflows that you can adopt within your organisation, but the one that’s used the most is the GitHub flow :

GitHub flow is a lightweight, branch-based workflow that supports teams and projects where deployments are made regularly.

Essentially, developers first create a branch from one of the long-lived development base branches, in which they perform necessary code changes. Once ready, a pull request (PR) is created, which initiates the review process made by other team members and in almost all cases triggers different application tests. If all code changes are in order, the pull request is accepted, or in other words, the changes are merged back into the base branch.

Organizing Branches

Besides adopting the GitHub flow explained above, another element to consider is the organization of your project’s Git branches. Similarly to how we’ve defined shared and isolated environments we can deploy into, your repository should also consist of shared and isolated branches that, in a way, mirror these environments.

Shared Branches

For your project, you might want to have a couple of shared and long-lived branches that represent your shared environments, like dev, staging, and prod (production). As with the environments, no strict naming rules exist, but these names are definitely something most developers will recognize. We recommend having these three as the minimum and, of course, if more are needed, you’re free to do so.

These branches should be made protected and direct code pushes into these should be disabled. Not only direct pushes break the GitHub flow and merging strategies we’re about to explain in the next section, in almost all cases, this triggers different deployment processes defined in your CI/CD workflows.

Finally, one of these branches will always be a starting point for every fix or a new feature that needs to be implemented. Usually, this is the dev branch which should be marked as the default branch in your repository.

Isolated (Development) Branches

With the shared and long-lived branches, depending on the project size, you always have a number of isolated or development, short-lived branches, that are created by developers and that, eventually, contain new fixes and features.

These branches are considered as short-lived because they exist for a shorter amount of time. As soon as the performed changes are merged into one of the long-lived branches, these branches can usually be immediately deleted.

As mentioned, the dev branch is usually the default branch, from which developers branch from, and to which the changes are ultimately merged back.

The following diagram shows both types of branches:

FAQ

Can We Adopt a Different Branching Strategy?

Yes, you can. The branching strategy presented in this guide is something that works in most cases. But, you’re free to define your own, if need be.

Can I Use a Different VCS?

Yes, you can. If you manage to define some best practices around it, we’d be glad to hear about it and add it to our documentation.