Skip to content

Update release guidance #7084

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
NickColley wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update release guidance #7084

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 23 additions & 24 deletions docs/releasing/after-publishing-a-release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,52 @@
# Tasks after publishing a new release of GOV.UK Frontend
# After publishing a new release of GOV.UK Frontend

Once we've published a new release of GOV.UK Frontend there are a number of things we still need to do, such as informing our community and updating our own repos.
After we've published a new release of GOV.UK Frontend, there are things we still need to do, such as inform our community and update our own repos.

## Update our repos to use the new release

Developers should update [govuk-design-system](https://github.com/alphagov/govuk-design-system) and [govuk-frontend-docs](https://github.com/alphagov/govuk-frontend-docs) to use the new release. When updating the design system, you should also test any new or updated guidance that relate to the new release and publish them along with the version update.
We should update [govuk-design-system](https://github.com/alphagov/govuk-design-system) and [govuk-frontend-docs](https://github.com/alphagov/govuk-frontend-docs) to use the new release. When updating the Design System, we should also check that:

## Let the community know about the new release
- any guidance updates are published and show as expected
- any updates coming from GOV.UK Frontend macro options show as expected

We now need to update our comms channels.
## Send an email to mailing list subscribers

### The mailing list
We usually send out an email with the release comms, except for releases with minor fixes.

The team should send out an email with the release comms drafted before publishing.

The release email should:
This email should:

- give a summary of the update
- explain on why teams should update
- components or styles affected (if possible)
- thanks to any major contributors (if possible, include name and organisation)
- explain why teams should update
- say which components or styles are affected (if applicable)
- thank any major contributors using their GitHub usernames

A release email will typically end with a link to the version's [release notes](https://github.com/alphagov/govuk-frontend/releases), and a call-to-action button to the [update npm how-to page](https://frontend.design-system.service.gov.uk/updating-with-npm/#update-using-node-js-package-manager-npm).

For example, see the [release email for GOV.UK Frontend 4.4.0](https://us1.admin.mailchimp.com/campaigns/show?id=10053738).
For example, see the [release email for GOV.UK Frontend 5.11.0](https://mailchi.mp/c877961d1db5/feature-release-govuk-frontend-v590-improved-file-upload-component-10977163?e=[UNIQID]).

### Slack
## Send Slack messages to relevant channels

We should update both internal and x-gov slack channels:
We should update both internal and cross-government Slack channels:

- [GDS: govuk-design-system](https://gds.slack.com/archives/CAF8JA25U)
- [GDS: digital-service-platforms](https://gds.slack.com/archives/C01E20X06JK)
- [x-gov: govuk-design-system](https://ukgovernmentdigital.slack.com/archives/C6DMEH5R6)

The message we send on Slack is usually a shorter version of the email.

We also need to review the GOV.UK Design System overview canvases we have on each support channel, updating the version number of GOV.UK Frontend in [GDS: #govuk-design-system](https://gds.slack.com/docs/T8GT9416G/F08UG2X7BFD) and [x-gov: #govuk-design-system](https://ukgovernmentdigital.slack.com/docs/T04V6EBTR/F058W5T94ET)
We should also review the GOV.UK Design System overview canvases we have on each support channel, updating the version number of GOV.UK Frontend in [GDS: #govuk-design-system](https://gds.slack.com/docs/T8GT9416G/F08UG2X7BFD) and [x-gov: #govuk-design-system](https://ukgovernmentdigital.slack.com/docs/T04V6EBTR/F058W5T94ET).

### Design System website
## Update the Design System website

We should check if we need to update the following places on the website:
We should decide whether we need to update the following places on the website:

- the "what's new" section on the homepage of the website. The content for this section can be found in [/views/partials/\_whats-new.njk](https://github.com/alphagov/govuk-design-system/blob/main/views/partials/_whats-new.njk).
- the aliases section in the metadata of the [Upcoming components and patterns page](https://github.com/alphagov/govuk-design-system/blob/main/src/community/upcoming-components-patterns/index.md?plain=1) to ensure that if a release includes a new component that searches for that component on the website no longer point at that page
- the "What's New" section on the homepage of the website - the content for this section can be found in [/views/partials/\_whats-new.njk](https://github.com/alphagov/govuk-design-system/blob/main/views/partials/_whats-new.njk)
- the aliases section in the metadata of the [Upcoming components and patterns page](https://github.com/alphagov/govuk-design-system/blob/main/src/community/upcoming-components-patterns/index.md?plain=1) to make sure that searches on the website for a new component no longer point at that page

## Clear the decks
## Tidy up our issue list and sprint board

Finally, we should make sure that our issue list and sprint board are tidy by making sure:
Finally, we should tidy up our issue list and sprint board by making sure:

- issues created for this release are all complete, closed, and moved into the **Done** column on the [Design System cycle board](https://github.com/orgs/alphagov/projects/53)
- that all the issues (on the same board) solved and/or published in this release have been moved from the **Ready to Release** column to **Done**
- issues created for this release are all complete, closed and moved into the **Done** column on the [Design System cycle board](https://github.com/orgs/alphagov/projects/53)
- all the issues on the cycle board that were closed in this release have been moved from the **Ready to Release** column to **Done**
- any associated milestones are closed
40 changes: 23 additions & 17 deletions docs/releasing/before-publishing-a-release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,49 @@
# Tasks before publishing a new release of GOV.UK Frontend
# Before publishing a new release of GOV.UK Frontend

When preparing to publish a release of GOV.UK Frontend we need to ensure we are following proper procedure to effectively track our work and are prepared to publish our new release.
When preparing to publish a release of GOV.UK Frontend, we need to make sure we’re:

following proper procedures to effectively track our work
ready to publish our new release

## Kick off the release

The whole team should coordinate whether to publish a new release. Choose a team member to lead on the release, typically a developer.
The whole team should decide whether to publish a new release, then choose a developer to lead on the release.

We next need to define a cutoff date for this release. Once the cutoff date passes, do not add any further major changes. We can still add small fixes before we publish as long as we notify the team. However, we should try to avoid adding too many fixes in this way, as it requires us to have to repeat steps of the release process.
We then need to set a cutoff date for this release. Once the cutoff date passes, do not add any further major changes. We can still add small fixes before we publish as long as we notify the team. However, we should try to avoid adding too many fixes in this way, as it would mean redoing steps of the release process.

## Raise an issue for the release

Use the '🚀 Release' issue template to [create an issue in the govuk-frontend repository](https://github.com/alphagov/govuk-frontend/issues/new/choose) tracking the tasks for this release.
Use the '🚀 Release' issue template to [create an issue in the govuk-frontend repository](https://github.com/alphagov/govuk-frontend/issues/new/choose) to track the tasks for this release.

The template lists the main tasks that happen for every release. If the release at hand needs some specific steps, make sure to add items to the lists for each of them, especially:
The template lists the main tasks we do for every release. If the release needs some specific tasks, make sure to add items to the lists for each of them, especially:

- merging documentation [PRs on govuk-design-system](https://github.com/alphagov/govuk-design-system/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen)
- merging documentation [PRs on govuk-frontend-docs](https://github.com/alphagov/govuk-frontend-docs/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen)
- merging [documentation PRs on govuk-design-system](https://github.com/alphagov/govuk-design-system/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen)
- merging [documentation PRs on govuk-frontend-docs](https://github.com/alphagov/govuk-frontend-docs/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen)

This issue should be:
Add this release issue to:

- added to the [Design System cycle board](https://github.com/orgs/alphagov/projects/53) backlog
- added to that release's milestone if there's one
- the [Design System cycle board](https://github.com/orgs/alphagov/projects/53) backlog
- the release's milestone, if it exists

## Draft comms and release notes for the community

A content designer and/or tech writer should do the following:
A content designer and/or technical writer should do the following:

- write announcements for Slack posts and email, including which channels to use
- write content to go on the Design System website after we release GOV.UK Frontend (for example, [draft comms for the Cookie banner component](https://docs.google.com/document/d/1jVyMB7i94NOeflWaf3kE4Q4APMXGfluK3rOh74IHO08/edit))
- gather the list of contributors to the release and make sure we thank them in the comms and release notes, tagging their GitHub username

- write announcements for slack posts, email and to go on the design system website after we release GOV.UK Frontend (for example, [draft comms for the cookie banner component](https://docs.google.com/document/d/1jVyMB7i94NOeflWaf3kE4Q4APMXGfluK3rOh74IHO08/edit))
- check who the release’s contributors are and if we have consent to include their name
## Get release notes ready to publish

A technical writer should finalise draft of release notes. Release notes will require a 2i review by another technical writer, make sure the technical writer has time to coordinate this. When ready, open a pull request to update the [CHANGELOG.md](https://github.com/alphagov/govuk-frontend/blob/main/CHANGELOG.md) file with the updated release notes.
A technical writer should finalise the draft of the release notes. Release notes will need a 2i review, so make sure the technical writer has time to coordinate this. When ready, open a pull request to update the [CHANGELOG.md](https://github.com/alphagov/govuk-frontend/blob/main/CHANGELOG.md) file with the updated release notes.

If the technical writer is unavailable, ask for help in the [gds-technical-writing Slack channel](https://gds.slack.com/archives/CAD0R2NQG) or confer with a content designer.
If a technical writer is unavailable, ask a content designer for help. If a content designer is unavailable, request help in the [gds-technical-writing Slack channel](https://gds.slack.com/archives/CAD0R2NQG).

The team should also post a message on any relevant [issue discussions](https://github.com/orgs/alphagov/projects/43/views/1) with rationale for any decisions we've made.

## Finalise the release

At this stage, the person leading the release should agree the publishing date. Once the team agrees, this confirms a code and content freeze. Use the [#design-system-team-channel](https://gds.slack.com/app_redirect?channel=design-system-team-channel) to confirm sign-off from:
At this stage, the developer leading the release should agree on the publishing date with the rest of the team, then confirm a date for a code freeze. Use the [#design-system-team-channel](https://gds.slack.com/app_redirect?channel=design-system-team-channel) to confirm sign-off from the:

- content designer, technical writer and designers for guidance, examples and community backlog decision rationale
- technical writer and developers for Nunjucks macros
Expand Down
30 changes: 15 additions & 15 deletions docs/releasing/publishing-a-preview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Publishing a preview of GOV.UK Frontend

This preview guidance is aimed at Design System team members. If you're an external contributor who needs to create a preview, please [contact the Design System team](https://design-system.service.gov.uk/contact/) and we'll do it for you.
This preview guidance is aimed at Design System team members. If you're an external contributor who needs to create a preview, [contact the Design System team](https://design-system.service.gov.uk/contact/), and we'll do it for you.

Before you publish a preview, you need to have committed a code change to GOV.UK Frontend. Then follow these instructions.
To publish a preview, you must first commit a change to GOV.UK Frontend.

Use previews when you:

Expand All @@ -14,36 +14,36 @@ Use previews when you:

## What happens when you preview GOV.UK Frontend

When you preview GOV.UK Frontend, this creates a GitHub branch. This branch contains the GOV.UK Frontend [`/packages/govuk-frontend`](/packages/govuk-frontend) directory with your trial changes.
Previewing GOV.UK Frontend creates a GitHub branch. This branch contains the GOV.UK Frontend [`/packages/govuk-frontend`](/packages/govuk-frontend) directory with your trial changes.

Projects can point to this branch in their package.json, instead of to the published [GOV.UK Frontend npm package](https://www.npmjs.com/package/govuk-frontend). No changes are published to the GOV.UK Frontend npm package as part of this process.

## Publish a preview

1. Run `git checkout -b BRANCH-NAME` to check out a new branch you want to preview, or `git checkout BRANCH-NAME` to check out an existing branch.

2. Make any required changes and commit them.
1. Make any required changes and commit them.

3. Ensure you're running the version of NodeJS matching [`.nvmrc`](/.nvmrc).
- If you use NVM, run `nvm use` to set up the right version
- If you use another management system (like [`asdf`](https://asdf-vm.com/guide/getting-started.html)), compare the output of `node --version` and install the right one if necessary
1. Make sure you're running the version of Node.js matching [`.nvmrc`](/.nvmrc).
- If you use NVM, run `nvm use` to set up the correct version
- If you use another management system (like [`asdf`](https://asdf-vm.com/guide/getting-started.html)), compare the output of `node --version` and install the correct one if necessary

4. Run `npm ci` to make sure you have the exact dependencies installed.

5. Run `npm run publish-preview` to create and push a new branch that contains your changes. This process may take a few moments and will display a `Success!` message.
1. Run `npm run publish-preview` to create and push a new branch that contains your changes - this process may take a few moments and will display a `Success!` message.

## Preview your changes

1. If you need to update an existing project to use the preview, copy the command that displays after the `Success!` message.

2. Navigate to the project in the command line and run the success notification command. Running this command makes the project point to the preview branch, instead of to the published [GOV.UK Frontend npm package](https://www.npmjs.com/package/govuk-frontend). You can now preview your trial changes to GOV.UK Frontend.
1. Navigate to the project in the command line and run the success notification command - running this command makes the project point to the preview branch, instead of to the published [GOV.UK Frontend npm package](https://www.npmjs.com/package/govuk-frontend).

1. You can now preview your trial changes to GOV.UK Frontend.

## Update a preview

1. Check out the Git branch you previously previewed (this is the branch you work on, not the branch the script created).
1. Check out the Git branch you previewed earlier (this is the branch you work on, not the branch the script created).

2. Make the required changes and commit them.
1. Make the required changes and commit them.

3. Follow steps 3-5 in [Publish a preview](#publish-a-preview).
1. Follow steps 3 to 4 in [Publish a preview](#publish-a-preview).

4. Follow the steps in [Preview your changes](#preview-your-changes).
1. Follow the steps in [Preview your changes](#preview-your-changes).
Loading
Loading