Merge pull request #4000 from alphagov/publish-preview-branch

Rename GitHub branch early releases to “previews”

CONTRIBUTING.md

@@ -79,7 +79,7 @@ See the versioning documentation for [updating the changelog](/docs/contributing
 
 ## Testing a release
 
-If you need to test a release, for example if you're contributing a new component see [Publishing pre-release of GOV.UK Frontend](/docs/releasing/publishing-a-pre-release.md).
+If you need to test a release, for example if you're contributing a new component see [Publishing a preview of GOV.UK Frontend](/docs/releasing/publishing-a-preview.md).
 
 ## Application tasks
 

bin/pre-release.sh → bin/publish-preview.sh

@@ -2,7 +2,10 @@
 set -e
 
 CURRENT_BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
-BRANCH_NAME="pre-release-$CURRENT_BRANCH_NAME"
+CURRENT_VERSION=$(npm run version --silent --workspace govuk-frontend)
+
+BRANCH_NAME="preview-$CURRENT_BRANCH_NAME"
+VERSION="$CURRENT_VERSION-$CURRENT_BRANCH_NAME"
 
 # Check if there are files that need to be commited
 if [[ -n $(git status --porcelain) ]]; then
@@ -22,10 +25,15 @@ git checkout -b $BRANCH_NAME
 # Build the package as normal
 npm run build:package
 
+echo "✍️ Update package version"
+npm version $VERSION --allow-same-version --no-git-tag-version --workspace govuk-frontend
+git add packages/govuk-frontend/package.json
+git add package-lock.json
+
 echo "✍️ Force commit package"
 git add --force packages/govuk-frontend/dist/
 git add --force packages/govuk-frontend/govuk-prototype-kit.config.json
-git commit --allow-empty -m "Release GOV.UK Frontend to '$BRANCH_NAME' for testing"
+git commit --allow-empty -m "Release GOV.UK Frontend 'v$VERSION' to '$BRANCH_NAME' for testing"
 
 # Create a local branch containing the packages/govuk-frontend directory
 echo "✨ Filter the branch to only the packages/govuk-frontend/ directory..."

docs/releasing/publishing-a-preview.md

@@ -0,0 +1,46 @@
+# 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/get-in-touch/) 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.
+
+Use previews when you:
+
+- [work on developing a component or pattern](https://design-system.service.gov.uk/community/develop-a-component-or-pattern/) for the GOV.UK Design System
+- want to trial an experimental feature (guidance on trialing experimental features is in development)
+
+> **Warning** Your projects should never depend on a preview GOV.UK Frontend package. This is because someone could remove the GitHub branch containing the preview package at any time. For this reason, never use a preview package in a production setting.
+
+## 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.
+
+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.
+
+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 exact dependencies installed.
+
+5. Run `npm run 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.
+
+## 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).
+
+2. Make the required changes and commit them.
+
+3. Follow steps 3-5 in [Publish a preview](#publish-a-preview).
+
+4. Follow the steps in [Preview your changes](#preview-your-changes).

package.json

@@ -19,7 +19,7 @@
     "start": "npm run dev",
     "build-release": "./bin/build-release.sh",
     "publish-release": "./bin/publish-release.sh",
-    "pre-release": "./bin/pre-release.sh",
+    "publish-preview": "./bin/publish-preview.sh",
     "predev": "npm run build",
     "dev": "concurrently \"npm run dev --workspace govuk-frontend-review\" \"npm run dev --workspace govuk-frontend\" --kill-others --names \"app,pkg\" --prefix-colors \"red.dim,blue.dim\"",
     "build": "npm run build --workspace govuk-frontend --workspace govuk-frontend-review",

packages/govuk-frontend/package.json

@@ -50,7 +50,8 @@
     "build:package": "gulp build:package --color",
     "build:release": "gulp build:release --color",
     "build:stats": "npm run stats --workspace govuk-frontend-stats",
-    "dev": "gulp dev --color"
+    "dev": "gulp dev --color",
+    "version": "echo $npm_package_version"
   },
   "devDependencies": {
     "@babel/core": "^7.22.9",