chore: Enable beta releases to NPM

Whilst it is possible to install this package from GitHub,
it can be useful to install from NPM as the published package structure varies slightly.

With this change, we will be able to publish to the `beta` channel by update the `beta` branch.
This will enable us to to install our experimental changes from NPM with:

```
npm install @guardian/cdk@beta
```

.github/workflows/cd.yaml

@@ -3,6 +3,7 @@ on:
   push:
     branches:
       - main
+      - beta
 jobs:
   CD:
     runs-on: ubuntu-latest
@@ -25,11 +26,12 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        # see https://github.com/tschaub/gh-pages/issues/345
-        run: |
-          git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
-          ./script/cd
-      - name: post-release
+        run: ./script/cd
+
+      # Only performed if `main` is updated
+      # See https://docs.github.com/en/actions/reference/environment-variables#determining-when-to-use-default-environment-variables-or-contexts
+      - if: ${{ github.ref == 'refs/heads/main' }}
+        name: post-release
         uses: guardian/[email protected]
         with:
           # This action will raise a PR to edit package.json.

README.md

@@ -105,6 +105,7 @@ To release a new version:
    - Release a new version to npm and update `package.json`.
 1. Enjoy a comment on your PR to inform you that your change has been released.
 
+For more information, see the docs on [testing][docs-testing].
 
 <!-- only links below here -->
 [badge-cd]: https://github.com/guardian/cdk/actions/workflows/cd.yaml/badge.svg
@@ -114,6 +115,8 @@ To release a new version:
 [directory-docs]: ./docs
 [directory-script]: ./script
 
+[docs-testing]: ./docs/006-testing.md
+
 [internal-cd-file]: https://github.com/guardian/cdk/actions/workflows/cd.yaml
 [internal-discussions]: https://github.com/guardian/cdk/discussions
 [internal-website]: https://guardian.github.io/cdk/

docs/006-testing.md

@@ -29,9 +29,32 @@ You can use the [CDK Playground][cdk-playground] stack to test your changes agai
 
 This stack isn't user facing. Accidentally causing destruction there is ok - better there than on theguardian.com!
 
+### Would your change update the layout of the NPM package?
+It can sometimes be necessary to update the layout of the NPM package.
+
+These changes can be quite difficult to simulate locally using `npm link` or similar.
+
+For this reason, it can be helpful to publish a beta version to NPM. To do so:
+  1. Update the `beta` branch
+  1. Wait for the robots (GitHub Actions) to run and release a beta version
+
+You can now install and test your changes with:
+
+```
+npm install @guardian/cdk@beta
+```
+
+Once you're happy with your changes, raise a PR into `main` as normal.
+
+NOTE: The `beta` branch is just like any other branch - it may not be up to date with `main`.
+It's wise to rebase it with `main` before working on it.
+
+For more information, see the [semantic-release docs][semantic-release-docs]
+
 <!-- only links below here -->
 [internal-testing-adr]: ./architecture-decision-records/004-testing.md
 [internal-integration-project]: ../tools/integration-test
 [internal-integration-project-stack]: ../tools/integration-test/src/integration-test-stack.ts
 
 [cdk-playground]: https://github.com/guardian/cdk-playground
+[semantic-release-docs]: https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/distribution-channels.md

release.config.js

@@ -1,5 +1,11 @@
 module.exports = {
-  branches: ["main"],
+  branches: [
+    // commits to the `main` branch will be released to npm as normal
+    { name: "main" },
+
+    // commits to the `beta` branch will be released to `@guardian/cdk@beta`
+    { name: "beta", prerelease: true },
+  ],
   plugins: [
     "@semantic-release/commit-analyzer",
     "@semantic-release/release-notes-generator",

script/cd

@@ -9,4 +9,11 @@ npm run build
 npm run test
 npm run lint
 npm run release
-npm run release:docs
+
+# Update the docs site only when `main` is updated
+if [ $GITHUB_REF = "refs/heads/main" ]; then
+  # see https://github.com/tschaub/gh-pages/issues/345
+  git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
+
+  npm run release:docs
+fi