Using Git

Overview

git is a distributed version-control system. It’s distributed, in that there’s no central source of truth. Each copy of a repository can contain the entire history, and be considered an authoritative source. But we tend to use it in a centralised fashion, treating the version that is hosted on GitHub as the shared central version, and basing all work against that copy.

It has excellent tools for branching and merging. Branching is possible in other version control systems, but merging can be very painful. This made people tentative about using that workflow.

In git, that problem goes away.

Tutorials

How-to

Set up to start contributing

Do not fork – clone a repo from https://github.com/ministryofjustice to your local machine.

Work locally

Create a branch to work in for your changes.

Before you create a branch, it’s worth considering the branch names and how you think the branch might become visible to other people.

A common prefix can be useful for categorising branches, and working with tools for continuous integration. Naming branches such as feature/foo, feature/bar, and bug/fix-column-migration can help other people in the team understand whether it’s a feature (new behaviour) or a fixing a bug. Having a common prefix can also work well with continuous integration tools such as Travis, which might be instructed to only do certain actions on branches named feature/* versus the main branch.

Other approaches:

feature/{JIRA-issue}-{description} – this change is for the Jira issue LM-6, and also has a human-readable description to give people more context. Also, one or more people might be working on this branch (pairing, or separately)
jabley/thing – this branch contains work that developer known as jabley is doing. Other people might not want to rely on this branch, since it might be force-pushed (but nicely please!)

Commit locally regularly

This can help to get to the point where you have a working version, and then want to try adding a new thing. Try to aim for each commit to be an atomic unit that delivers a non-broken version of the code-base. As you make more changes, consider whether it should be separate commit, or an amendment to the last one. You can always interactively rebase your changes to edit the commit history to a logical changeset.

Push your changes regularly

This protects you from local hardware failure, and ensures you don’t lose your changes.

Request a review

Once you have got to the point where you consider the change complete, you should open a pull request on GitHub, asking for the changes to be reviewed by someone else on the team.

Review pull requests

Before commenting on a pull request, ensure you know how the person would prefer to get feedback. This might involve asking them first. Feedback options include face-to-face, pairing, via email/Slack, or commenting on a pull request.

Ideally, continuous integration should be set up to provide some feedback on a pull request (the tests pass, coding style has been followed etc). If not, you’ll probably want to pull the code and try it out for yourself.