/fwang/aws-cdk

Wiki directory

Browse AI-generated documentation for any repository.

Versioning and Stability

Relevant source files

The following files were used as context for generating this wiki page:

The AWS Cloud Development Kit (AWS CDK) employs a structured versioning and stability model to manage the evolution of its APIs and provide clear expectations for developers. This system distinguishes between stable and experimental modules, ensuring that developers can build reliable infrastructure while also having access to the latest AWS features.

Modules in the AWS Construct Library are categorized with a stability designation. Once a module is marked as "Stable," it adheres to Semantic Versioning (SemVer), where breaking API changes are reserved for major version releases. In contrast, "Experimental" modules may introduce breaking changes in any release, allowing for rapid iteration and feedback. This dual approach balances the need for a dependable core library with the ability to innovate and expand AWS service coverage.

Sources: README.md:36-44

Module Stability Levels

Each package within the AWS CDK is assigned a stability and maturity level in its package.json file. These fields define the contract with the user regarding API stability and support. The pkglint tool enforces consistency between these settings and the content of the package's README.md.

Sources: tools/pkglint/lib/rules.ts:200-333

The following table describes the different maturity and stability levels used across the project:

Maturity / Stability	Description	Example `package.json`
`stable`	The module's API is considered stable. It follows semantic versioning, and breaking changes are only introduced in major versions.	`packages/@aws-cdk/aws-s3-assets/package.json`
`experimental`	The module is under active development. APIs are subject to non-backward compatible changes or removal in any future version.	`packages/@aws-cdk/aws-waf/package.json`
`cfn-only`	The package contains only auto-generated L1 constructs (CloudFormation resources). These classes are always considered stable.	`packages/@aws-cdk/aws-waf/package.json`
`developer-preview`	A more advanced stage of `experimental`, indicating the module is approaching stability but may still have changes.	`packages/awslint/package.json`
`deprecated`	The module is no longer recommended for use and may be removed in a future major version.	`packages/@aws-cdk/assets/package.json`

Sources: packages/@aws-cdk/aws-s3-assets/package.json:101, packages/@aws-cdk/aws-waf/package.json:96-97, packages/awslint/package.json:60-61, packages/@aws-cdk/assets/package.json:99-100

Stability Banners

The README.md file for each package must include a stability banner that reflects its maturity level. This is automatically validated and can be fixed by the pkglint tool.

For example, an experimental module's README.md will contain a banner like this:

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes.

Sources: packages/@aws-cdk/example-construct-library/README.md:3-11, tools/pkglint/lib/rules.ts:258-290

A package containing only L1 (CFN) resources will have a banner indicating their stability:

All classes with the Cfn prefix in this module ([CFN Resources]) are always stable and safe to use.

Sources: packages/@aws-cdk/cfnspec/build-tools/create-missing-libraries.ts:236-242

Breaking Change Policy

The project has a strict policy against introducing breaking changes into stable modules. This policy is enforced through automated checks in the pull request process.

Sources: tools/prlint/lint.ts:113-119

PR Linting for Stability

A PR linter automatically checks pull requests to prevent breaking changes in stable modules. The assertStability function is a key part of this validation.

// file: tools/prlint/lint.ts:113-119
function assertStability(title: string, body: string) {
  const breakingStable = breakingModules(title, body)
    .filter(mod => 'stable' === moduleStability(findModulePath(mod)))

  if (breakingStable.length > 0) {
    throw new Error(`Breaking changes in stable modules [${breakingStable.join(', ')}] is disallowed.`);
  }
}

Sources: tools/prlint/lint.ts:113-119

The following diagram illustrates the PR validation flow for breaking changes.

Generating architecture diagram...

This diagram shows how the PR linter detects breaking changes and checks the stability of the affected modules.

Sources: tools/prlint/lint.ts:100-119

Conventional Commits

Breaking changes must be clearly indicated in commit messages using the "BREAKING CHANGE:" footer, as per the Conventional Commits specification. This is used by the release tooling to generate changelogs and identify major version bumps.

The format must be precise. For example, variations like "BREAKING CHANGES:" are not allowed.

// file: tools/prlint/lint.ts:100-108
function validateBreakingChangeFormat(title: string, body: string) {
  const re = /^BREAKING.*$/m;
  const m = re.exec(body);
  if (m) {
    if (!m[0].startsWith('BREAKING CHANGE: ')) {
      throw new LinterError(`Breaking changes should be indicated by starting a line with 'BREAKING CHANGE: ', variations are not allowed. (found: '${m[0]}')`);
    }
...

Sources: tools/prlint/lint.ts:100-108, tools/cdk-release/test/changelog.test.ts:112-122

Release and Changelog Generation

The project uses a cdk-release tool to automate version bumping and changelog generation based on Conventional Commits.

Sources: tools/cdk-release/lib/index.ts:1-24

Version Management

The current version of the project is stored in a central file, which is read by the release tool. The tool calculates the next version (stableVersion and alphaVersion) based on the types of commits since the last release (e.g., a commit with BREAKING CHANGE: triggers a major version bump).

Sources: tools/cdk-release/lib/index.ts:26-33

Changelog Generation

Changelogs are generated automatically from Git history. The process parses conventional commits and groups them into sections like "Features", "Bug Fixes", and "BREAKING CHANGES".

A key aspect of changelog generation is the handling of changes to experimental modules. The experimentalChangesTreatment option controls this behavior.

Option	Description
`INCLUDE`	(Default) All changes, including those to experimental modules, are included in the main changelog.
`STRIP`	Changes related to experimental modules are excluded from the changelog.
`SEPARATE`	Changes to stable modules go into the main changelog, while changes to experimental modules go into a separate alpha changelog (e.g., `CHANGELOG.alpha.md`).

Sources: tools/cdk-release/test/changelog.test.ts:33-80

The following diagram shows the changelog generation workflow.

Generating architecture diagram...

This flow demonstrates how the release tooling can produce different changelog artifacts based on the stability of the changes.

Sources: tools/cdk-release/test/changelog.test.ts:33-109

An example of a generated changelog entry for a feature and a breaking change:

## [1.24.0](https://github.com/aws/aws-cdk/compare/v1.23.0...v1.24.0)

### ⚠ BREAKING CHANGES TO EXPERIMENTAL FEATURES

* this is a breaking change

### Features

* super important feature

Sources: tools/cdk-release/test/changelog.test.ts:124-138

Versioning and Stability

Relevant source files

The following files were used as context for generating this wiki page:

Sources: README.md:36-44

Module Stability Levels

Sources: tools/pkglint/lib/rules.ts:200-333

The following table describes the different maturity and stability levels used across the project:

Maturity / Stability	Description	Example `package.json`
`stable`	The module's API is considered stable. It follows semantic versioning, and breaking changes are only introduced in major versions.	`packages/@aws-cdk/aws-s3-assets/package.json`
`experimental`	The module is under active development. APIs are subject to non-backward compatible changes or removal in any future version.	`packages/@aws-cdk/aws-waf/package.json`
`cfn-only`	The package contains only auto-generated L1 constructs (CloudFormation resources). These classes are always considered stable.	`packages/@aws-cdk/aws-waf/package.json`
`developer-preview`	A more advanced stage of `experimental`, indicating the module is approaching stability but may still have changes.	`packages/awslint/package.json`
`deprecated`	The module is no longer recommended for use and may be removed in a future major version.	`packages/@aws-cdk/assets/package.json`

Sources: packages/@aws-cdk/aws-s3-assets/package.json:101, packages/@aws-cdk/aws-waf/package.json:96-97, packages/awslint/package.json:60-61, packages/@aws-cdk/assets/package.json:99-100

Stability Banners

The README.md file for each package must include a stability banner that reflects its maturity level. This is automatically validated and can be fixed by the pkglint tool.

For example, an experimental module's README.md will contain a banner like this:

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes.

Sources: packages/@aws-cdk/example-construct-library/README.md:3-11, tools/pkglint/lib/rules.ts:258-290

A package containing only L1 (CFN) resources will have a banner indicating their stability:

All classes with the Cfn prefix in this module ([CFN Resources]) are always stable and safe to use.

Sources: packages/@aws-cdk/cfnspec/build-tools/create-missing-libraries.ts:236-242

Breaking Change Policy

The project has a strict policy against introducing breaking changes into stable modules. This policy is enforced through automated checks in the pull request process.

Sources: tools/prlint/lint.ts:113-119

PR Linting for Stability

A PR linter automatically checks pull requests to prevent breaking changes in stable modules. The assertStability function is a key part of this validation.

// file: tools/prlint/lint.ts:113-119
function assertStability(title: string, body: string) {
  const breakingStable = breakingModules(title, body)
    .filter(mod => 'stable' === moduleStability(findModulePath(mod)))

  if (breakingStable.length > 0) {
    throw new Error(`Breaking changes in stable modules [${breakingStable.join(', ')}] is disallowed.`);
  }
}

Sources: tools/prlint/lint.ts:113-119

The following diagram illustrates the PR validation flow for breaking changes.

Generating architecture diagram...

This diagram shows how the PR linter detects breaking changes and checks the stability of the affected modules.

Sources: tools/prlint/lint.ts:100-119

Conventional Commits

The format must be precise. For example, variations like "BREAKING CHANGES:" are not allowed.

// file: tools/prlint/lint.ts:100-108
function validateBreakingChangeFormat(title: string, body: string) {
  const re = /^BREAKING.*$/m;
  const m = re.exec(body);
  if (m) {
    if (!m[0].startsWith('BREAKING CHANGE: ')) {
      throw new LinterError(`Breaking changes should be indicated by starting a line with 'BREAKING CHANGE: ', variations are not allowed. (found: '${m[0]}')`);
    }
...

Sources: tools/prlint/lint.ts:100-108, tools/cdk-release/test/changelog.test.ts:112-122

Release and Changelog Generation

The project uses a cdk-release tool to automate version bumping and changelog generation based on Conventional Commits.

Sources: tools/cdk-release/lib/index.ts:1-24

Version Management

Sources: tools/cdk-release/lib/index.ts:26-33

Changelog Generation

Changelogs are generated automatically from Git history. The process parses conventional commits and groups them into sections like "Features", "Bug Fixes", and "BREAKING CHANGES".

A key aspect of changelog generation is the handling of changes to experimental modules. The experimentalChangesTreatment option controls this behavior.

Option	Description
`INCLUDE`	(Default) All changes, including those to experimental modules, are included in the main changelog.
`STRIP`	Changes related to experimental modules are excluded from the changelog.
`SEPARATE`	Changes to stable modules go into the main changelog, while changes to experimental modules go into a separate alpha changelog (e.g., `CHANGELOG.alpha.md`).

Sources: tools/cdk-release/test/changelog.test.ts:33-80

The following diagram shows the changelog generation workflow.

Generating architecture diagram...

This flow demonstrates how the release tooling can produce different changelog artifacts based on the stability of the changes.

Sources: tools/cdk-release/test/changelog.test.ts:33-109

An example of a generated changelog entry for a feature and a breaking change:

## [1.24.0](https://github.com/aws/aws-cdk/compare/v1.23.0...v1.24.0)

### ⚠ BREAKING CHANGES TO EXPERIMENTAL FEATURES

* this is a breaking change

### Features

* super important feature

Sources: tools/cdk-release/test/changelog.test.ts:124-138