Update release guidance

Based on the changes made to the release process in the
[improve the release process epic](#6676)

Co-authored-by: Calvin Lau <77630796+calvin-lau-sig7@users.noreply.github.com>
Co-authored-by: domoscargin <domoscargin@users.noreply.github.com>
Co-authored-by: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>

Author: 4 people

docs/releasing/after-publishing-a-release.md

@@ -1,53 +1,51 @@
-# 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:
+- any guidance updates are published and show as expected
+- any updates coming from GOV.UK Frontend macro options show as expected
 
-## Let the community know about the new release
+## Send an email to mailing list subscribers
 
-We now need to update our comms channels.
+We usually send out an email with the release comms, except for releases with minor fixes.
 
-### The mailing list
-
-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

docs/releasing/before-publishing-a-release.md

@@ -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

docs/releasing/publishing-a-preview.md

@@ -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:
 
@@ -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).