Generate NPM tag within publish-release bash script

bin/generate-npm-tag.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+set -e
+
+# Get highest tag published on Github
+HIGHEST_PUBLISHED_VERSION=$(git tag --list 2>/dev/null | sort -V | tail -n1 2>/dev/null | sed 's/v//g')
+
+# Extract tag version from ./package/package.json
+CURRENT_VERSION=$(node -p "require('./package/package.json').version")
+
+function version() { echo "$@" | awk -F. '{ printf("%d%03d%03d\n", $1,$2,$3); }'; }
+
+if [ $CURRENT_VERSION == $HIGHEST_PUBLISHED_VERSION ]; then
+  echo "⚠️ Git tag $TAG already exists. Check you have updated the version in package/package.json correctly."
+  exit 1
+elif [ $(version $CURRENT_VERSION) -ge $(version $HIGHEST_PUBLISHED_VERSION) ]; then
+  NPM_TAG="latest"
+else
+  major_version_num="${CURRENT_VERSION:0:1}"
+  NPM_TAG="latest-$major_version_num"
+fi

bin/publish-release.sh

@@ -1,14 +1,29 @@
 #!/bin/sh
 set -e
 
+source ./bin/generate-npm-tag.sh
+
+# Check NPM tag looks as expected
+# https://npm.github.io/publishing-pkgs-docs/updating/using-tags.html#publishing-with-tags
+echo "This will publish the package with the following NPM tag:"
+echo $NPM_TAG
+echo " "
+
+read -r -p "Does this look correct? [y/N] " continue_prompt
+
+if [[ $continue_prompt != 'y' ]]; then
+    read -r -p "What should the NPM tag be: " NPM_TAG
+fi
+
 echo "Starting a release..."
 echo " "
 echo "This will:"
 echo "- check that you're logged in to npm as the correct user"
-echo "- publish the package if it has not been published already"
-echo "- check that there is not already a tag published"
-echo "- create a new tag"
-echo "- push the tag to remote origin"
+echo "- publish the package to NPM if it has not been published already"
+echo "- tag the package on NPM with '$NPM_TAG'"
+echo "- check that there is not already a Github tag published"
+echo "- create a new Github tag"
+echo "- push the Github tag to remote origin"
 echo "- create a zip file of the 'dist/' directory locally"
 echo " "
 
@@ -34,7 +49,7 @@ echo "📦  Publishing package..."
 
 # Try publishing
 cd package
-npm publish
+[ $NPM_TAG = "latest" ] && npm publish || npm publish --tag $NPM_TAG
 echo "🗒 Package published!"
 cd ..
 

docs/releasing/publishing-from-a-support-branch.md

@@ -1,11 +1,10 @@
 # Publishing from a support branch
 
-This document is for GOV.UK Design System developers who need to publish a support branch of GOV.UK Frontend when the `main` branch contains unreleasable changes. For example, you might need to release a fix as part of a:
+This document is for GOV.UK Design System developers who need to publish a support branch of GOV.UK Frontend. For example, you might need to release a fix as part of a:
 
 - patch release, after the team has started to merge changes for a new feature release into the `main` branch - for example, a 3.14.x release once we've started merging changes for 3.15.0
-- release, after the team has started to merge changes for a new breaking release into the `main` branch - for example, a 3x.x release once we've started merging changes for 4.0.0
-
-Do not use this document to release changes for previous major releases. We have not tested the document in this scenario, and extra work would be needed to tell npm not to mark the release as the 'latest'.
+- release, after the team has started to merge changes for a new breaking release into the `main` branch - for example, a 3.x.x release once we've started merging changes for 4.0.0
+- release for a previous major version - for example, a 4.x.x release after we've released 5.0.0
 
 If you want to publish the `main` branch for GOV.UK Frontend, [follow the steps in Publishing GOV.UK Frontend](/docs/releasing/publishing.md).
 
@@ -55,7 +54,7 @@ Note: Before you go on annual leave, tell the delivery manager who will be looki
 
 ### Change the code
 
-1. To check out the support branch for the current major release, run `git checkout support/<CURRENT MAJOR VERSION NUMBER>.x`. If the branch does not exist, follow these steps to create it:
+1. Find out which major version this release will be targeting, for example, if you're releasing v4.x.x, the major version is version 4. To check out the support branch for that major version, run `git checkout support/<MAJOR VERSION NUMBER>.x`. If the branch does not exist, follow these steps to create it:
 
     - make sure you have all tags locally by running `git fetch --all --tags --prune`
     - run `git checkout tags/v<LAST RELEASED VERSION NUMBER> -b support/<CURRENT MAJOR VERSION NUMBER>.x` - for example, `git checkout tags/v3.9.1 -b support/3.x`
@@ -64,21 +63,21 @@ Note: Before you go on annual leave, tell the delivery manager who will be looki
 
 3. Push the support branch to GitHub. The branch will automatically have branch protection rules applied.
 
-4. To fix the issue, create a new branch (for example, `git checkout -b fix-the-thing`) from the `support/<CURRENT MAJOR VERSION NUMBER>.x` branch.
+4. Create a new branch for your code changes (for example, `git checkout -b fix-the-thing`) from the `support/<MAJOR VERSION NUMBER>.x` branch.
 
 5. Run `npm install` to make sure you have the latest dependencies installed.
 
 6. Make your code changes, and test them following our [standard testing requirements](/docs/contributing/testing.md).
 
 7. Update the changelog with details of the fix.
 
-8. Commit your changes, then push your new branch (see step 4) to GitHub and raise a pull request, with `support/<CURRENT MAJOR VERSION NUMBER>.x` as the base branch to merge into.
+8. Commit your changes, then push your new branch (see step 4) to GitHub and raise a pull request, with `support/<MAJOR VERSION NUMBER>.x` as the base branch to merge into.
 
-9. Once a developer approves the pull request, merge it into `support/<CURRENT MAJOR VERSION NUMBER>.x`. It’s usually a developer who reviews the pull request, but sometimes pull requests need an extra review from another role. For example, if the pull request involves a design change, you may need a review from a designer.
+9. Once a developer approves the pull request, merge it into `support/<MAJOR VERSION NUMBER>.x`. It’s usually a developer who reviews the pull request, but sometimes pull requests need an extra review from another role. For example, if the pull request involves a design change, you may need a review from a designer.
 
 ### Build a new release
 
-1. Check out `support/<CURRENT MAJOR VERSION NUMBER>.x`.
+1. Check out `support/<MAJOR VERSION NUMBER>.x`.
 
 2. Create and check out a new branch, `support-release-[version-number]`. The version number of the new release depends on the type of release. New features correspond to a minor (X.1.X) change - for example, '3.14.0 (Feature release)'. Fixes correspond to a patch (X.X.1) change - for example, '3.13.1 (Patch release)'. In either case, refer to the previous release of that kind, and give the new release the logical next number. To learn more about our versioning, see our [guidance on updating the changelog](/docs/contributing/versioning.md#updating-changelog).
 
@@ -100,21 +99,27 @@ Note: Before you go on annual leave, tell the delivery manager who will be looki
 
   You will now be prompted to continue or cancel.
 
-9. Raise a pull request, with `support/<CURRENT MAJOR VERSION NUMBER>.x` as the base branch to merge into.
+9. Raise a pull request, with `support/<MAJOR VERSION NUMBER>.x` as the base branch to merge into.
 
-10. Once a developer approves the pull request, merge it into `support/<CURRENT MAJOR VERSION NUMBER>.x`.
+10. Once a developer approves the pull request, merge it into `support/<MAJOR VERSION NUMBER>.x`.
 
 ### Publish the release to npm
 
-1. Check out `support/<CURRENT MAJOR VERSION NUMBER>.x` and pull the latest changes.
+1. Check out `support/<MAJOR VERSION NUMBER>.x` and pull the latest changes.
 
 2. Sign in to npm (`npm login`), using the npm/govuk-patterns-and-tools team [credentials](https://github.com/alphagov/design-system-team-credentials/tree/main/npm/govuk-patterns-and-tools).
 
-3. Run `npm run publish-release`, which will prompt you to either continue or cancel. Enter `y` to continue.
+3. Run `npm run publish-release`, which will prompt you to check whether the npm tag looks as expected.
+
+  If you're publishing a release for a previous major version, do not tag this release as the 'latest' release on npm. Instead, give the tag the format `latest-[major-version-number]`, for example, `latest-4`.
+
+  Enter `y` to continue. If you think the tag should be different, enter `N` to have the option to set your own npm tag.
+
+4. You will now be prompted to continue or cancel the release. Check the details and enter `y` to continue. If something does not look right, press `N` to cancel the release.
 
 4. View the created tag in the [GitHub interface](https://github.com/alphagov/govuk-frontend/releases) as follows:
 
-    - select the latest tag
+    - select the most recent tag
     - press **Edit tag**
     - set ‘GOV.UK Frontend v[version-number]’ as the title
     - add release notes from changelog
@@ -132,7 +137,7 @@ Note: Before you go on annual leave, tell the delivery manager who will be looki
     - move any relevant issues from the 'Ready to Release' column to 'Done'
     - close any associated milestones
 
-## Update the `main` branch
+## Update the `main` branch (optional)
 
 1. Check out the `main` branch and pull the latest changes.
 

docs/releasing/publishing.md

@@ -78,17 +78,24 @@ Developers should pair on releases. When remote working, it can be useful to be
 
 2. Sign in to npm (`npm login`), using the npm/govuk-patterns-and-tools team [credentials](https://github.com/alphagov/design-system-team-credentials/tree/main/npm/govuk-patterns-and-tools).
 
-3. Run `npm run publish-release`, which will prompt you to either continue or cancel. Enter `y` to continue.
+3. Run `npm run publish-release`, which will prompt you to check whether the NPM tag looks as expected.
 
-4. View the created tag in the [Github interface](https://github.com/alphagov/govuk-frontend/releases) as follows:
+  If you're following these instructions, you're probably doing a sequential release, meaning
+  the tag should be 'latest'.
+
+  Enter `y` to continue. If you think the tag should be different, enter `N` to have the option to set your own NPM tag.
+
+4. You will now be prompted to continue or cancel the release. Check the details and enter `y` to continue. If something does not look right, press `N` to cancel the release.
+
+5. View the created tag in the [Github interface](https://github.com/alphagov/govuk-frontend/releases) as follows:
   - select the latest tag
   - press **Create release from tag**
   - set 'GOV.UK Frontend v[version-number]' as the title
   - add release notes from changelog
   - attach the generated ZIP that has been generated at the root of this project
   - publish release
 
-5. Run `npm logout` to log out from npm.
+6. Run `npm logout` to log out from npm.
 
 # After you publish the new release