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 Desktop & GitHub) to help you version control code.
You Could - With your team, agree and design a version control workflow. Use (Git, Github desktop & 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 and Github Desktop - (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.
Github Desktop is an app that simplifies using Git. The app allows you to interact with github via a graphical interface which allows you to perform common git commands without the hassle of using the command line.
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 Desktop & GitHub Effectively
To make effective use of Git, Github Desktop and GitHub:
Familiarise yourself with git! The ‘happy git with r’ book has lots of good material, helpful for users of all languages:
- It has a good introduction to git fundamentals,
- …as well as a set of daily workflows.
You could check out A Quick Guide to Git & GitHub, published by the Information Services Division at National Services Scotland.
You could check out Getting started with Github desktop, for an overview of how to set up and use.
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.
See the appendix for a general approach to version control at GAD.
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 GADHUB
GADHUB is GAD’s github organisation and the place where we store our code repositories. You will need a GitHub account before you can join and get access to GADHUB. Once you have created you account (please use a gad email address and using a handle that includes you name) let the Development team know and they can sent you an invite to join.
For the time being repos on GADHUB are, for the most part, private. This is so we can better manage access to the repos.
1.8 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.