diff --git a/bin/generate-npm-tag.sh b/bin/generate-npm-tag.sh new file mode 100644 index 0000000000..f2ed842155 --- /dev/null +++ b/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 diff --git a/bin/publish-release.sh b/bin/publish-release.sh index f278f62de4..e0320f31c5 100755 --- a/bin/publish-release.sh +++ b/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 .. diff --git a/docs/releasing/publishing-from-a-support-branch.md b/docs/releasing/publishing-from-a-support-branch.md index 8342477413..9c36556109 100644 --- a/docs/releasing/publishing-from-a-support-branch.md +++ b/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/.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/.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 -b support/.x` - for example, `git checkout tags/v3.9.1 -b support/3.x` @@ -64,7 +63,7 @@ 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/.x` branch. +4. Create a new branch for your code changes (for example, `git checkout -b fix-the-thing`) from the `support/.x` branch. 5. Run `npm install` to make sure you have the latest dependencies installed. @@ -72,13 +71,13 @@ Note: Before you go on annual leave, tell the delivery manager who will be looki 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/.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/.x` as the base branch to merge into. -9. Once a developer approves the pull request, merge it into `support/.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/.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/.x`. +1. Check out `support/.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/.x` as the base branch to merge into. +9. Raise a pull request, with `support/.x` as the base branch to merge into. -10. Once a developer approves the pull request, merge it into `support/.x`. +10. Once a developer approves the pull request, merge it into `support/.x`. ### Publish the release to npm -1. Check out `support/.x` and pull the latest changes. +1. Check out `support/.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. diff --git a/docs/releasing/publishing.md b/docs/releasing/publishing.md index fd588d7903..366e71c667 100644 --- a/docs/releasing/publishing.md +++ b/docs/releasing/publishing.md @@ -5,7 +5,7 @@ 2. Developers to raise new issues in the team GitHub repositories ([govuk-frontend](https://github.com/alphagov/govuk-frontend), [govuk-frontend-docs](https://github.com/alphagov/govuk-frontend-docs), [govuk-prototype-kit](https://github.com/alphagov/govuk-prototype-kit)) to: - draft comms for the new release (example issue: [#2507](https://github.com/alphagov/govuk-frontend/issues/2507)) - create release notes for the new release (example issue: [#2508](https://github.com/alphagov/govuk-frontend/issues/2508)) - - release the new version of GOV.UK Frontend to NPM (example issue: [#2509](https://github.com/alphagov/govuk-frontend/issues/2509)) + - release the new version of GOV.UK Frontend to npm (example issue: [#2509](https://github.com/alphagov/govuk-frontend/issues/2509)) - update the GOV.UK Design System to use the new release of GOV.UK Frontend (example issue: [#2024](https://github.com/alphagov/govuk-design-system/issues/2024)) - update the GOV.UK Frontend Docs to use the new release of GOV.UK Frontend (example issue: [#184](https://github.com/alphagov/govuk-frontend-docs/issues/184)) - post the comms and do tidy-up tasks (example issue: [#2510](https://github.com/alphagov/govuk-frontend/issues/2510)) @@ -78,9 +78,16 @@ 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 @@ -88,7 +95,7 @@ Developers should pair on releases. When remote working, it can be useful to be - 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