Principle 1 Use Version Control

Version control your code so you and your collaborators can track changes over time, trace back errors, and retrieve old versions. Version control will help you make changes and improvements to your code with confidence.

You Must - Use version control and follow guidance on coding in the open.

You Should - Use standard tools (Git & GitHub) to help you version control code.

You Could - With your team, agree and design a version control workflow. Use (Git & GitHub) collaboratively and effectively.

Related Areas: Demonstrably Correct,
Be Reproducible

1.1 What is version control?

Version control is managing changes to the documents and files which make up your work. This typically includes a system for identifying versions (i.e. a version number or name) and some sort of log of what the changes are, who made them and when they were made. Version control systems are usually associated with tools for comparing, restoring and merging versions.

1.2 Git - (program for version control)

Git is the most popular way to version control code. You can tell Git to keep track of a folder full of code (a repository or 'repo'). As you make changes, Git identifies them and asks which should be kept (or 'committed'), and for a comment identifying why. It uses this to maintain a log of all the changes. This log can be used to restore old versions.

1.3 GitHub - (service for storing code version controlled using git)

GitHub is the most popular place to store git repositories. Storing your repository on GitHub has some key benefits:

  • It acts as a backup of your code & its history.
  • Other people can see your code, download it and collaborate with you.

As such, using a service like GitHub is a good way to ensure that your code is available to your team, and that knowledge is transferred.

1.4 Using Git & GitHub Effectively

To make effective use of Git and GitHub:

  • Familiarise yourself with git! The 'happy git with r' book has lots of good material, helpful for users of all languages:

  • You could check out A Quick Guide to Git & GitHub, published by the Information Services Division at National Services Scotland.

  • Follow the GDS Git Style Guide

  • Commit code in small chunks, as often as possible, and write a descriptive comment with each commit. This makes your repository much more useful in the future and is called doing 'atomic commits'.

  • Commit changes using an account which is specific to you. This means that it is clear in future who changed what.

1.5 Version Control Workflow

Define a version control workflow which explains how you use git as a team. This could include how you use branches, how you merge changes and how to handle pull requests.

1.6 Code in the Open

GitHub repositories can be open (shared with anyone) or private (shared only with selected collaborators).

The Technology Code of Practice encourages us to 'be open and use open source'. As such, code should be open unless there is a good reason for it not to be.

Good reasons for code to be private might be that it includes classified material, or information on an unreleased policy. GDS have published guidance on this for both external, and internal use.

1.7 Manual Version Control

It is possible to manually keep track of your code by systematically keeping copies of your code as you modify it and maintaining a corresponding log of all changes to the code. The log should include: What has changed, why, and a link to the relevant copy of the files. It is recommended to use version control tools (git) instead of this manual process.

1.8 Git & GitHub at DHSC

At present, DHSC base machines do not have git. If you have access to a developer account you can install git for windows from: git-scm.com It is anticipated that in the near future TAP (The Analytical Platform) will provide git functionality for all analysts within the department.