Staying up to date with changes
Staying up to date with the latest version of GOV.UK Frontend helps make sure your service:
- continues to look, feel and behave consistently with GOV.UK
- benefits from the latest accessibility and usability improvements
- works correctly in the latest browsers and assistive technologies, and benefits from any new improvements made possible in those versions
As with all software dependencies, you should have a plan to regularly update GOV.UK Frontend as part of the ongoing maintenance of your service.
Getting updates when we publish a new release
To make sure you’re notified when we publish a new release, you can:
- watch the govuk-frontend repository on GitHub
- join the #govuk-design-system Slack channel
- sign up for email updates
- use an automated dependency monitoring tool like Dependabot
Find out which version you’re currently using
If you installed GOV.UK Frontend using npm, find out which version of GOV.UK Frontend you’re using by running npm list govuk-frontend from the root of your project:
$ npm list govuk-frontend your_project@/path/to/your/project └──email@example.com
Understanding what has changed
How to interpret the version numbering and the release notes.
How the version numbering works
GOV.UK Frontend’s version number follows the format
PATCH are numbers.
We aim to follow semantic versioning. This means we will:
- increase the
PATCHnumber if a release only includes bug fixes, for example going from v4.6.0 to v4.6.1
- increase the
MINORnumber and reset the
PATCHnumber to 0 if a release includes new features, for example going from v4.6.1 to v4.7.0
- increase the
MAJORnumber and reset the
PATCHnumbers to 0 if a release might require you to make changes to your service when you update (see breaking changes), for example going from v4.7.0 to v5.0.0
The intention is to make sure you can easily update to new minor and patch releases without needing to make any changes to your service.
However, what you consider a breaking change can depend on how you are using GOV.UK Frontend in your service. You should always read the release notes and test your service when upgrading to a new version.
Using the release notes
We publish release notes for every release. They document the changes we’ve made, including both technical and design changes.
When upgrading to a newer version of GOV.UK Frontend you should read all the release notes from the version you are currently using, up to and including the version you are upgrading to.
The release notes can be quite long, especially for new major versions. It’s important to read them carefully, but you might find many of the changes do not affect your service.
We’ll only include breaking changes in major releases.
Breaking changes might require you to take some action so your service continues to work.
You might find many of the breaking changes do not affect you, especially if you have a process for dealing with deprecations and upgrading versions when upgrading between minor and patch releases.
Some breaking changes involve making changes to your HTML. If you’re using our Nunjucks macros to generate the HTML for your service, the changes are usually automatically applied.
We might include recommended changes in any release.
You do not need to make recommended changes for your service to keep working, but these changes often provide improvements of some kind. For example, making something more accessible.
We’ll only include new features in major or minor releases.
Some features will require you to make changes to your service, if you want to use them.
We might include deprecations in any release.
We deprecate things to communicate a future breaking change, usually scheduled to be made in the next major version.
For example, we would deprecate something in v4.6.0 before we remove it in v5.0.0 at which point we would include it as a breaking change in the release notes.
If you deal with deprecations as they come up you can reduce the amount of work required to upgrade to the next major version.
We might include fixes in any release.
Fixes include bug fixes and small improvements that do not require you to do anything.
If a fix requires you to do something, we will include it as a recommended or breaking change.
Updating to the latest version
Once you know what has changed, you’re ready to upgrade to the latest version.
You’re responsible for making sure your service continues to work as expected after upgrading.
You might want to consider using automated testing or visual regression tests to increase your confidence and minimise the amount of manual testing required.
Updating to the latest version if you installed GOV.UK Frontend using npm
To update to the most recent version, run:
npm install govuk-frontend@latest
If you want to install an earlier version, replace latest with the version that you want to update to. For example:
npm install firstname.lastname@example.org
Updating to the latest version if you installed GOV.UK Frontend using precompiled files
Follow the instructions for installing using precompiled files, replacing any files that already exist.