Merge pull request #4001 from alphagov/backport-npm-version

[support/4.x] Backport: Publishing docs changes, versioning

Author: colinrotherham

bin/build-release.sh

@@ -1,9 +1,9 @@
 #!/bin/sh
 set -e
 
-# Check if there are unexpected changes. Changes to CHANGELOG.md and the
-# package.json file are expected as part of the normal release process.
-changes="$(git status --porcelain -- ':!CHANGELOG.md' ':!package/package.json')"
+# Check if there are unexpected changes. Changes to CHANGELOG.md, package.json
+# and package-lock.json files are expected as part of the normal release process.
+changes="$(git status --porcelain -- ':!CHANGELOG.md' ':!package/package.json' ':!package-lock.json')"
 if [[ -n $changes ]]; then
   echo "⚠ Unexpected changes in your working directory:"
   echo "$changes"
@@ -35,7 +35,7 @@ TAG="v$ALL_PACKAGE_VERSION"
 CURRENT_BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
 
 if [ $(git tag -l "$TAG") ]; then
-    echo "⚠️ Git tag $TAG already exists. Check you have updated the version in package/package.json correctly."
+    echo "⚠️ Git tag $TAG already exists. Check you have run `npm version` correctly."
     exit 1;
 else
     git add .

bin/generate-npm-tag.sh

@@ -10,7 +10,7 @@ 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."
+  echo "⚠️ Git tag $TAG already exists. Check you have run `npm version` correctly."
   exit 1
 elif [ $(version $CURRENT_VERSION) -ge $(version $HIGHEST_PUBLISHED_VERSION) ]; then
   NPM_TAG="latest"

docs/contributing/testing.md

@@ -139,7 +139,7 @@ To make sure your changes work in the Design System, use `npm link` to test befo
 cd ../govuk-design-system
 git checkout main
 git pull
-npm install # note running `npm install` after `npm link` will destroy the link.
+npm ci # note running `npm ci` after `npm link` will destroy the link.
 npm link ../govuk-frontend/package/
 ```
 

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

@@ -25,7 +25,7 @@ Projects can point to this branch in their package.json, instead of to the publi
 
 3. Run `nvm use` to make sure you’re using the right version of Node.js and npm.
 
-4. Run `npm ci` to make sure you have the correct dependencies installed.
+4. Run `npm ci` to make sure you have the exact dependencies installed.
 
 5. Run `npm run pre-release` to create and push a new branch that contains your changes. This process may take a few moments and will display a `Success!` message.
 

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

@@ -35,7 +35,7 @@ Read the docs for [what to do before publishing a release](/docs/releasing/befor
 
 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.
+5. Run `npm ci` to make sure you have the exact dependencies installed.
 
 6. Make your code changes, and test them following our [standard testing requirements](/docs/contributing/testing.md).
 
@@ -53,25 +53,35 @@ Read the docs for [what to do before publishing a release](/docs/releasing/befor
 
 3. Run `nvm use` to make sure you’re using the right version of Node.js and npm.
 
-4. Run `npm install` to make sure you have the latest dependencies installed.
+4. Run `npm ci` to make sure you have the exact dependencies installed.
 
-5. In the CHANGELOG.md, replace the 'Unreleased' heading with the new version number and its release type. For example, '3.14.1 (Fix release)'. Also add a new 'Unreleased' heading above this new heading, so people raising new pull requests know where to add them in the changelog.
+5. Update the [`CHANGELOG.md`](../../CHANGELOG.md) by:
 
-6. Update the `package/package.json` version with the new version number.
+   - changing the 'Unreleased' heading to the new version number and its release type. For example, '3.14.1 (Fix release)'
+   - adding a new 'Unreleased' heading above the new version number and release type, so users will know where to add PRs to the changelog
+   - saving your changes
 
-7. Save the changes. Do not commit.
+6. Apply the new version number by running:
 
-8. Run `npm run build-release` to:
+   ```
+   npm version <NEW VERSION NUMBER> --no-git-tag-version --workspace package
+   ```
 
-- build GOV.UK Frontend into the `/package` and `/dist` directories
-- commit the changes
-- push a branch to GitHub
+   This step will update the `package.json` and project `package-lock.json` files.
 
-  You will now be prompted to continue or cancel.
+   Do not commit the changes.
 
-9. Raise a pull request, with `support/<MAJOR VERSION NUMBER>.x` as the base branch to merge into.
+7. Run `npm run build-release` to:
 
-10. Once a developer approves the pull request, merge it into `support/<MAJOR VERSION NUMBER>.x`.
+   - build GOV.UK Frontend into the `/package` and `/dist` directories
+   - commit the changes
+   - push a branch to GitHub
+
+   You will now be prompted to continue or cancel.
+
+8. 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/<MAJOR VERSION NUMBER>.x`.
 
 ### Publish the release to npm
 
@@ -106,7 +116,7 @@ Read the docs for [what to do after publishing a release](/docs/releasing/after-
 
 1. Check out the `main` branch and pull the latest changes.
 
-2. Run `nvm use` and `npm install` to make sure you have the latest dependencies installed.
+2. Run `nvm use` and `npm ci` to make sure you have the exact dependencies installed.
 
 3. Make the same changes as in the patch fix pull request, and test them using our [standard testing requirements](/docs/contributing/testing.md). Remember that `main` will contain changes the support branch did not have, which might affect the code changes you’ll need to make.
 

docs/releasing/publishing.md

@@ -10,18 +10,33 @@ Developers should pair on releases. When remote working, it can be useful to be
 
 2. Run `nvm use` to make sure you're using the right version of Node.js and npm.
 
-3. Run `npm install` to make sure you have the latest dependencies installed.
+3. Run `npm ci` to make sure you have the exact dependencies installed.
 
 4. Create and check out a new branch (`release-[version-number]`). See the [versioning documentation](/docs/contributing/versioning.md) for more information.
 
 5. Update the [`CHANGELOG.md`](../../CHANGELOG.md) by:
 
-   - changing the 'Unreleased' heading to the new version-number and release-type - for example, '3.11.0 (Feature release)'
-   - adding a new 'Unreleased' heading above the new version-number and release-type, so users will know where to add PRs to the changelog
+   - changing the 'Unreleased' heading to the new version number and release type. For example, '3.11.0 (Feature release)'
+   - adding a new 'Unreleased' heading above the new version number and release type, so users will know where to add PRs to the changelog
+   - saving your changes
 
-6. Update [`package/package.json`](../../package/package.json) version with the new version-number.
+6. Apply the new version number by running:
 
-7. Save the changes. Do not commit.
+   ```
+   npm version <NEW VERSION NUMBER> --no-git-tag-version --workspace package
+   ```
+
+   This step will update the `package.json` and project `package-lock.json` files.
+
+   Do not commit the changes.
+
+7. Update browser data from ["Can I use"](https://caniuse.com) by running:
+
+   ```
+   npx update-browserslist-db@latest
+   ```
+
+   This step will update the project `package-lock.json` file if updates are found.
 
 8. Run `npm run build-release` to:
 
@@ -32,7 +47,7 @@ Developers should pair on releases. When remote working, it can be useful to be
    You will now be prompted to continue or cancel.
 
 9. Create a pull request and copy the changelog text.
-   When reviewing the PR, check that the version-numbers have been updated and that the compiled assets use this version-number.
+   When reviewing the PR, check that the version numbers have been updated and that the compiled assets use this version number.
 
 10. Once a reviewer approves the pull request, merge it to **main**.