Contributing

April 24, 2026 ยท View on GitHub

We encourage all contributors to read this document fully.

The Guardian has a Code of Conduct for all contributors, which can be found here.

Local setup

We follow the script/task pattern, find useful scripts within the script directory for common tasks.

  • ./script/setup to install dependencies
  • ./script/start to run the Jest unit tests in watch mode
  • ./script/start-docs to generate documentation and view in the browser
  • ./script/lint to lint the code using ESLint
  • ./script/test to run the Jest unit tests
  • ./script/build to compile TypeScript to JS
  • ./script/cli-docs to update the CLI documentation in this file

There are also some other commands defined in package.json:

  • npm run lint --fix attempt to autofix any linter errors
  • npm run format format the code using Prettier
  • npm run watch watch for changes and compile

However, it's advised you configure your IDE to format on save to avoid horrible "correct linting" commits.

Development Environment

This project comes with a devcontainer.json file. This enables use of development containers in compatible IDEs. The devcontainer files were built with devenv and can be altered with the same tool.

Decision Records

Architecture Decisions Records are files where we can document the decisions we make around any form of structure, architecture or approach. By documenting them in this way, we can preserve the thought process behind all the decisions whilst also laying out formally the preferences for all developers working on the library.

The docs/architecture-decision-records directory contains the records for @guardian/cdk.

Development principles

Tests

Use direct assertions for constructs and snapshots for patterns (and stacks). See the Testing ADR for fuller discussion here.

Backwards compatibility

Releases will automatically bump versions as required.

At the time of writing, the library is still quite subject to breaking changes. However, bear in mind that breaking changes, particularly those to our core patterns, create migration burden for our teams; avoid them where possible.

In the near-future we are likely to adopt a stricter approach in this area.

Testing larger changes

Depending on the nature of your change, you may want to test things on a 'real' stack.

This section describes a few ad-hoc testing methods, posed as questions.

Would your change present a clear API for users?

One of the aims of this library is to abstract the complexities of AWS behind a simple API.

You can use the integration test project to test changes:

  • Start watching changes to the library npm run watch
  • Setup the integration test project cd integration-test && npm i
  • Add your pattern/construct to the stack
  • Update the library as needed

Would your change cause resource replacement?

Another aim of this library is to enable the safe migration of existing stacks.

There are a number of stateful resources in AWS, for example:

  • databases holding data
  • load balancers with CNAMEs in DNS with a long TTL
  • S3 buckets holding data

You can use the CDK Playground stack to test your changes against a real AWS stack.

This stack isn't user facing. Accidentally causing destruction there is ok - better there than on theguardian.com!

Releasing

We use changesets to automate NPM releases.

You will be prompted to add a changeset (if necessary) after raising your PR.