From 76131cc6c62c7bafb7387fc6e1373ee13b07bfa0 Mon Sep 17 00:00:00 2001 From: Rico Huijbers Date: Mon, 17 Mar 2025 11:16:30 +0100 Subject: [PATCH] docs: compatibility table for CLI/library versions Describe the compatibility model, and add a table linking the CLI and library versions. --- COMPATIBILITY.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 9 +++++ 2 files changed, 102 insertions(+) create mode 100644 COMPATIBILITY.md diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 000000000..fae954e62 --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,93 @@ +# CDK CLI and AWS Construct Library compatibility table + +The table below show what version of the CDK CLI is required for a particular +version of the AWS Construct Library: + +The table below contains the specific versions of the schema, along with the +CLI that supports them and the Construct Library that uses them. + +| Library version | Minimum CLI Version | Schema Version | +|-----------------|---------------------|----------------| +| 2.174.0 | 2.174.0 | 39 | +| 2.182.0 | 2.1000.0 | 40 | +| (unreleased) | 2.1003.0 | 41 | + +How to use this table: find your library version in the leftmost column. +If it's not in there, find the highest version lower than your library version. +The middle column indicates the minimum version of the CDK CLI you need to use. + +## How it works + +(This section describes how the protocol between App and CLI is versioned and +is purely for reference; the table above contains the most important information.) + +The compatibility between the construct library and the CLI is based on the +version of the [Cloud Assembly Schema](./packages/@aws-cdk/cloud-assembly-schema) +used by the construct library and supported by the CLI app. The app writes +a particular version `X` of the Cloud Assembly, and the CLI can read all versions +up to and including the version `Y` that was current when it was released. We +need `X <= Y`. + +``` +┌────────┐ ┌─────────┐ ┌──────────┐ +│ │ (writes) │ │ (reads) │ │ +│ App │─────────▶│ cdk.out │◀──────────│ CLI │ +│ │ │ │ │ │ +└────────┘ schema └─────────┘ schemas └──────────┘ + vX <= vY +``` + +### Compatibility rule for CLI < 2.1000.0 + +Before CDK CLI `2.1000.0`, the CLI and the library were released in lockstep +with the same version number, and so the versions `X` and `Y` above are the +same for a given version number. + +An easy compatibility rule therefore is: the CLI supports apps written against +the AWS Construct Library with the same version or lower. It might support more +versions as well, but it *at least* supports those. + +This works because `v(App) <= v(CLI)` guarantees that `X <= Y`. + +### Compatibility rule for CLI >= 2.1000.0 + +Since CDK CLI `2.1000.0`, the CLI and construct library have two different +versions. The only rule that relates `X` and `Y` involves the *release date* of +the respective packages. The CLI version that supports a particular schema version +is always released before a CDK app starts emitting cloud assemblies using +that schema. + +A general rule therefore is: a particular library version's Cloud Assemblies +are supported by the CLI that is current at the time of the library's release, +as well as every newer CLI version. It might be supported by older versions, but +it is *at least* supported by those. + +This works because the CLI that is current at time of release of a +particular library version can always handle the output of that library +version and every version before it. + +In a visual example: + +``` + this CLI version... + ⋎ + o +CLI │ │ │ │ │ │ │ │ + ─────┬┴─────┴┬────┴──┬────┬─┴────┬──┴──────┴┬────┴───┬──┴───→ (time) +Library │ │ │ │ │ │ │ + ⋏ ⋏ ⋏ ⋏ ⋏ + ...supports at least these library versions +``` + +And the other way around: + +``` + this library version... + ⋎ + o +Library │ │ │ │ │ │ │ + ─────┴┬─────┬┴────┬──┴────┴─┬────┴──┬──────┬┴────┬───┴──┬────→ (time) +CLI │ │ │ │ │ │ │ │ + ⋏ ⋏ ⋏ ⋏ ⋏ + ...is supported by these CLI versions +``` diff --git a/README.md b/README.md index cb02e2bd1..355f7c2fe 100644 --- a/README.md +++ b/README.md @@ -62,3 +62,12 @@ Here are the packages in this repository. See the README of each package for mor Every package comes with its own unit tests. There is a companion repository to this one containing the integration tests. You can find it here: See the [contributing guide](./CONTRIBUTING.md) for more information on this repository. + +## Compatibility + +The CLI is always able to process CDK apps using a version of the Construct Library +released before it. We recommend you always keep the CLI version up-to-date to get the +latest features. + +For more details on the compatibility model and specific versions that work together, +see [COMPATIBILITY.md](COMPATIBILITY.md). \ No newline at end of file