Beta This is new guidance. Complete our quick 5-question survey to help us improve it.

  1. Service manual
  2. Technology
  3. Maintaining version control in coding

You must have a way to maintain version control for your code.

Version control means keeping track of changes to your code over time.

It allows you to:

  • revert to an earlier version whenever you want to
  • record your changes and the reasons why you made them, to help future developers understand the process
  • work on changes in parallel as a team before merging them together

Meeting the Digital Service Standard

You must maintain version control as part of meeting the following points:

You’ll have to discuss this in your service assessments.

Making commits

Making a commit means making a set of changes permanent. You should:

  • write clear commit messages
  • group changes according to their purpose
  • review new changes

Writing commit messages

You should commit any changes with a clear message explaining the change. Clear commit messages help new or future developers and the public to see the changes you’ve made.

Your commit messages should:

  • describe what you’ve changed and why
  • link to any supporting information like development stories, bug reports, or third party documentation

As well as describing what you’ve changed, your commit messages should also explain why. You should also include links to any supporting information like development stories, bug reports or third party documentation.

For example, if the change is helping to fix a bug in a certain browser, your commit message could be:

`Set cache headers

Browser-name was doing foo, so we need to do X. See http://example.com/why-is-this-broken for more details.`

Grouping changes

When updating code, you should make small separate commits of changes and group the changes according to their purpose.

For example, if you make several commits in order to fix a bug, you should group those changes together.

Reviewing changes

Whenever possible, you should review each others’ code. The process for this could change between teams, but make sure:

  • every code change is reviewed by someone who didn’t write it
  • the process doesn’t stop you from deploying software regularly or making quick bug fixes

Using distributed version control systems

You should use a distributed version control system so that:

  • everyone involved in the process has a full copy of the code and its history
  • it’s easier for developers to create ‘branches’ in their code to explore new features or approaches without encroaching on other work
  • developers can continue to work when the network is unavailable, making small incremental commits, merging their changes back with everyone else’s at a later date

The Government Digital Service (GDS) and many other government teams use a distributed version control system called Git.

Read about how GDS uses Git and check the GDS Git style guide.

Other uses for version control

You can also use version control in other parts of the work you’re doing to build your service.

For example, see how the World Wide Web Consortium (W3C) is using Git and GitHub to manage its specifications.

You may also find the Deploying software regularly guide useful.

Published by:
Technology community (backend development)
Last update:

Grouping changes and reviewing sub-sections added.

Grouping changes and reviewing sub-sections added.