Skip to main content
Table of contents

The GDS Way and its content is intended for internal use by the GDS community.

Writing release notes

When you publish a new version of your code, you should also publish a release note that tells users what’s changed and how to update from their current version.

You can publish a release note as either a:

Structure your release note so it has headings for:

  • breaking changes - where users must change their code to avoid it breaking after they update
  • new features
  • bug fixes

Write release notes in the GOV.UK style. See GOV.UK Frontend’s v3.0.0 release note as an example. Be clear and concise, use the active voice and address your users directly. You may want to get help from a technical writer.

Use an active verb-based heading for each change, and to group related changes. For example ‘Update file paths’.

For each change, start by telling your users directly how the change affects them. Start sentences with:

  • “You can now…”
  • “You can no longer…”
  • “You no longer need to…”
  • “The API now…” or “The API no longer… ” - if you need to talk about an element directly, for example when you’re describing a bug fix

For breaking changes, start sentences with:

  • “You should…”
  • “You can change…” - if it’s one of several options
  • “Change…” - if it’s the only option
  • “You must change…” - if something will go wrong otherwise

You should avoid:

  • writing from your team’s perspective - avoid “We’ve fixed…”, “We’ve added” or “Fixed a bug where…”
  • links to ‘further guidance’ - your release note should contain all the guidance that’s essential to updating
  • in-depth reasons for changes - add a link to a pull request, a blog post or your documentation instead
  • the passive voice
  • images

You should also write a README for GDS repositories.

Using code examples

You should only include ‘after’ code, not ‘before’ code. This means it’s easier for users to know which code to copy and paste, and to check if they’ve made the changes correctly.

Lead into a code example with either:

  • a colon - if it’s the exact code a user should use:

    In your assets path, add afolder/:

  • ‘For example’ - if the user’s code may be different to the example:

    Add an assets- prefix to data-module attribute values. For example:

    <div data-module="assets-section">

Guidance outside GDS

You can find more information from:

This page was last reviewed on 24 February 2020. It needs to be reviewed again on 24 August 2020 by the page owner #gds-way .
This page was set to be reviewed before 24 August 2020 by the page owner #gds-way. This might mean the content is out of date.