From d9924caadb60215f96b2d7e6e8e9cb3b5a2a71e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Mon, 23 Aug 2021 14:23:48 +0200 Subject: [PATCH 01/24] feat: jsii modular versioning This PR proposes a new way to model the `aws/jsii` project in order to alleviate friction in making significant changes to the platform, without compromising on key elements of the developer experience, or risking to unnecessarily fragment the ecosystem. --- text/0374-jsii-modular.md | 257 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 text/0374-jsii-modular.md diff --git a/text/0374-jsii-modular.md b/text/0374-jsii-modular.md new file mode 100644 index 000000000..2b2d9bbff --- /dev/null +++ b/text/0374-jsii-modular.md @@ -0,0 +1,257 @@ +# Modular jsii + +* **Original Author(s)**: @RomainMuller +* **Tracking Issue**: #374 +* **API Bar Raiser**: @{BAR_RAISER_USER} + +This RFC proposes to unlock (de-couple) the versions of all jsii packages +(i.e: compiler, code generators, runtimes, tools and libraries) in order to +enable introduction of new major versions of any of these packages without +necessarily incurring a new major version of all other packages. + +In order to make it easier to operate with de-coupled package versions, this RFC +further proposes we break the [aws/jsii](https://github.com/aws/jsii) mono-repo +into multiple single-package repositories. + +## Working Backwards + +### Release Notes entry + +```md +Future releases of the *jsii* package constellation will no longer follow an +all-at-once version increment strategy. Instead, each individual package will be +released under their own version line. It is hence no longer necessary to ensure +the version of all *jsii* packages in a product's dependency are aligned on the +exact same release. For example, it is now possible to have a dependency on the +`jsii` compiler at `4.3.0` while using `jsii-pacmak` at `1.35.0`, which +previously would have led to a fatal error when executing `jsii-pacmak`. + +BREAKING CHANGE: In order to allow developers to use the latest & greatest +features of TypeScript, the `jsii` compiler no longer follows semantic +versioning. Instead, releases are made in-line with those of the `typescript` +compiler, which does not follow semantic versioning. The TypeScript compiler +releases new language features (and often, syntax breaking changes) on each new +*major.minor* release. Future `jsii` releases will share the major and minor +version numbers with the `typescript` release they are built on (e.g: `jsii` +releases in the `4.3.x` line are built on top of series `4.3.x` of the +`typescript` compiler). +``` + +### `CONTRIBUTING` guides + +Each new repository will get a fresh `CONTRIBUTING.md` guide that includes the +following blurb (except for the repository for `@jsii/jsii-spec`): + +```md +This package is part of the *jsii* constellation. It is essential for this +package to consistently produce or consume `.jsii` assemblies according to the +specification defined by the [`@jsii/spec` package][@jsii/spec]. + +[@jsii/spec]: https://github.com/aws/jsii-spec +``` + +The `CONTRIBUTING.md` guide for the `@jsii/spec` package will have the following +blurb instead: + +```md +This package defines the shared interface between each package of the *jsii* +constellation. Changes made to this package must always be backwards compatible: +a new major version of `@jsii/spec` must retain the ability to correctly process +assemblies that were accepted by previous major versions. +``` + +### `README.md` for the `jsii` compiler + +````md +In order to allow developers to access and leverage the latest and greatest of +*TypeScript* language features, `jsii` compiler releases follow the `typescript` +package releases. For example, `jsii` version `4.3.x` is built on top of version +`4.3.x` of the `typescript` compiler. + +> IMPORTANT: As `typescript` package does not follow semantic versioning. +> Minor releases of the `typescript` compiler almost always include syntax +> breaking changes together with new language features. Since `jsii` now +> releases in line with `typescript` minor lines, `jsii` no longer adheres to +> semantic versioning. + +The `jsii` release notes for the initial release on each new *major.minor* line +will include a link to the corresponding TypeScript release notes entry, and a +description of any `jsii` breaking changes that may have been introduced with +the release. + +When setting up a `jsii` project, we recommend pinning the dependency on the +`jsii` compiler to the desired minor version line (which corresponds to the +`typescript` release line), using a `~` SemVer range: + +```js +{ + // ... + "devDependencies": { + // ... + "jsii": "~4.3.1", + // ... + }, + // ... +} +``` +```` + +--- + +Ticking the box below indicates that the public API of this RFC has been +signed-off by the API bar raiser (the `api-approved` label was applied to the +RFC pull request): + +``` +[ ] Signed-off by API Bar Raiser @xxxxx +``` + +## Public FAQ + +> This section should include answers to questions readers will likely ask about +> this release. Similar to the "working backwards", this section should be +> written in a language as if the feature is now released. +> +> The template includes a some common questions, feel free to add any questions +> that might be relevant to this feature or omit questions that you feel are not +> applicable. + +### What are we launching today? + +We are announcing a change in versioning strategy for the *jsii* constellation +of packages, which opens the way for an increased pace of innovation in the +*jsii* ecosystem: + +- Each package of the constellation now has it's own, independent version + number, and only gets a new release when a change was introduced; +- The `jsii` compiler now follows the `typescript` compiler version number, + allowing developers to easily leverage improvements in the *TypeScript* + language and compiler performance; +- The `@jsii/spec` package guarantees all releases of packages in the + constellation remain inter-operable going forward. + + +### Why should I use this feature? + +The new versioning strategy allows developers to have greater control over the +*jsii* tools they use. It allows developers to benefit from improvements to the +*TypeScript* language (and compiler performance) faster, by allowing them to +upgrade their project on their own timeline - in the same way they would be able +to do for a "pure" *TypeScript* project. + +Since all parts of the *jsii* constellation are inter-operable with all major +releases of the *jsii* packages, developers are able to opt into new and +improved code-generation features of `jsii-pacmak` on their own schedule (i.e: +when they release a new major version of their library) without requiring all +their dependencies and dependents use the same version of `jsii-pacmak`. + +## Internal FAQ + +### Why are we doing this? + +We are doing this to reduce the friction involved in making major changes to any +of the *jsii* constellation of packages. This will allow breaking changes to be +introduced in parts of the ecosystem without bumping the major version of the +rest of packages. + +This will improve our pace of innovation, as we will hence be able to introduce +a new major version of any part of the ecosystem wihtout necessarily requiring +all downstream consumers to migrate all at once. + +For example, this allows the `jsii` compiler to be upgraded to a new release +line of `typescript` without forcing every downstream consumer to also accept +the syntax breaking changes at the same time. Instead, consumers will be free +to take on a new release line of `jsii` independently from their dependencies as +well as from their consumers. + +Separating the mono-repository into multiple repositories will help ensure we +maintain backwards compatibility between individual packages, and reduce the +risk of creating codependent packages (different repositories need to be +released independenlty, so dependencies can only flow in an asyclic manner). +This will also make it easier for new contributors to approach *jsii*, as they +will be able to focus strictly on one package, instead of having the entire +constellation in their working set. + +### Why should we _not_ do this? + +Breaking up the mono-repository into multiple independent repositories will come +at a higher maintenance cost than having a single repository. The act of moving +code around will also require some time to be invested: there are currently +co-dependent relationships between certain packages (`jsii-pacmak` has a local +develooment dependency on the runtimes, and on the `jsii-calc` packages, etc...) +that will need to be broken. Additionally, some checks currently enforce that +all tools used to work on an assembly are on the same version line, which will +no longer be the case. + +### What is the technical solution (design) of this feature? + +The first component of implementing this RFC is to migrate code for various +tools and libraries to their own repository: + +- `@jsii/spec` and `jsii-reflect` (those can be combined as they have similar + purpose) +- `jsii` +- `jsii-pacmak` +- `jsii-rosetta` +- `@jsii/kernel` and `@jsii/runtime` (which could be combined into a single + package) +- Each individual `@jsii/*-runtime` package (and related tests) + +Those new repositories could be created within the `aws` GitHub organization, or +alternatively a new organization could be created (the `jsii` name is already in +use as a GitHub organization). + +The second component of this RFC is changing the release strategy for the `jsii` +compiler so that it follows `typescript` version lines (`major.minor`), and +ensuring other downstream consumers of `.jsii` assemblies do not attempt to +enforce version consistency using the `jsiiVersion` field. + +### Is this a breaking change? + +This is not a breaking change in the traditional sense: all existing code will +continue to work with the current release lines of all packages in the +ecosystem. However, the new versioning strategy of `jsii` is a departure from +Semantic Versioning, which will be accompanied with a major version change (from +`1.x` to `4.3.x` - matching the current `typescript` release line). This is to +be noted in the release ntoes. + +### What alternative solutions did you consider? + +An alternative to de-coupled versioning is to time breaking changes in the +*jsii* constellation with new major releases of the root consumer libraries +(`constructs`, `aws-cdk-lib`, ...), however this forgets to account for the +existence of other consumers of *jsii* which do not depend on these libraries, +and may hence not have the same drive to release a new major version at that +time. Additionally, such major releases are expected to be infrequent as they +represent a major burden on the community, meaning our ability to release +improvements to *jsii* packages would be severely limited. + +It would also be possible to unlock versions in the mono-repository, in order to +allow each packages to include breaking changes when necessary. However, this +makes it all too easy to inadvertently break backwards compatibility, as it is +so tempting to introduce the fix for a breaking change in the same PR as the +breaking change itself. Using several repositories makes this much less likely. + +### What are the drawbacks of this solution? + +This solution will increase the number of repositories that have to be monitored +for issues and feature requests, as well as for new contributions from members +of the community. + +It might also make the project as a whole more difficult to navigate, as it will +be spread over multiple packages, instead of being in a centralized location. + +### What is the high-level project plan? + +1. Determine the new repository naming scheme (which GitHub organization do we + use to host the repositories, what is the exact partition plan) +1. Extract the code for the `jsii` compiler, and start releasing with a + `major.minor` matching those of the underlying `typescript` release +1. Extract the code for the `jsii-pacmak` tool +1. Extract the code for the `@jsii/runtime` and `@jsii/kernel` packages +1. Extract the code for each `@jsii/*-runtime` package +1. Extract the remaining tools + +### Are there any open issues that need to be addressed later? + +- What GitHub organzaition or naming scheme will be used for these? From 8590666bb83efb9225ecbdf927e3c07ee5dbf357 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Mon, 23 Aug 2021 14:32:21 +0200 Subject: [PATCH 02/24] make linter happy --- text/0374-jsii-modular.md | 1 - 1 file changed, 1 deletion(-) diff --git a/text/0374-jsii-modular.md b/text/0374-jsii-modular.md index 2b2d9bbff..bce180345 100644 --- a/text/0374-jsii-modular.md +++ b/text/0374-jsii-modular.md @@ -130,7 +130,6 @@ of packages, which opens the way for an increased pace of innovation in the - The `@jsii/spec` package guarantees all releases of packages in the constellation remain inter-operable going forward. - ### Why should I use this feature? The new versioning strategy allows developers to have greater control over the From 0b874f12b83675d21358cb33a3085f0a1812f599 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Wed, 27 Apr 2022 15:12:53 +0200 Subject: [PATCH 03/24] explain why bring-your-own TypeScript is not an option --- text/0374-jsii-modular.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/text/0374-jsii-modular.md b/text/0374-jsii-modular.md index bce180345..93f05611d 100644 --- a/text/0374-jsii-modular.md +++ b/text/0374-jsii-modular.md @@ -216,6 +216,27 @@ be noted in the release ntoes. ### What alternative solutions did you consider? +#### Bring-your-own TypeScript version + +One of the main rationales for this change is to enable the use of new +TypeScript releases without forcing the enitre package ecosystem to make the +change at the same time (due to language-breaking changes). + +An option to address this would be to allow customers to "bring their own" +TypeScript compiler, by making it a `peerDependency`. This however comes with +two main challenges: + +- The TypeScript compiler API is not stable between TypeScript releases, and it + is hence not possible to author a `jsii` compiler that can leverage an + arbitrary TypeScript version. +- Declarations files emitted by different TypeScript compiler versions may not + be compatible with previous versions of TypeScript. Addressing this particular + issue would require all customers use a tool such as `downlevel-dts` to + produce declarations files compatible with previous iterations of TypeScript. + The `jsii` compiler is a better place to address this. + +#### Coordinating major versions with root consumers + An alternative to de-coupled versioning is to time breaking changes in the *jsii* constellation with new major releases of the root consumer libraries (`constructs`, `aws-cdk-lib`, ...), however this forgets to account for the @@ -225,6 +246,8 @@ time. Additionally, such major releases are expected to be infrequent as they represent a major burden on the community, meaning our ability to release improvements to *jsii* packages would be severely limited. +#### Unlock versions, but keep mono-repository + It would also be possible to unlock versions in the mono-repository, in order to allow each packages to include breaking changes when necessary. However, this makes it all too easy to inadvertently break backwards compatibility, as it is From 5d1e3d12c8421f153c3a4160a6efcc401487810a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Wed, 27 Apr 2022 15:17:12 +0200 Subject: [PATCH 04/24] Provide examples of things we cannot easily do today --- text/0374-jsii-modular.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/text/0374-jsii-modular.md b/text/0374-jsii-modular.md index 93f05611d..9f18ed08e 100644 --- a/text/0374-jsii-modular.md +++ b/text/0374-jsii-modular.md @@ -153,6 +153,14 @@ of the *jsii* constellation of packages. This will allow breaking changes to be introduced in parts of the ecosystem without bumping the major version of the rest of packages. +In particular, it is currently difficult to introduce breaking changes to the +compiler (such as: moving to a more recent version of TypeScript, adding new +compile-time validations that break existing code, removing behaviors such as +the peer dependencies update which are no longer desirable, dropping support for +older runtime versions, etc...), as bumping the major version of all packages +implies fragmenting the entire ecosystem (between what's been upgraded, and what +has not been upgraded). + This will improve our pace of innovation, as we will hence be able to introduce a new major version of any part of the ecosystem wihtout necessarily requiring all downstream consumers to migrate all at once. From 84ecb1505d5cbcb14b1717ab15cf2bc08b96dd41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Wed, 27 Apr 2022 15:21:30 +0200 Subject: [PATCH 05/24] typo fix --- text/0374-jsii-modular.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0374-jsii-modular.md b/text/0374-jsii-modular.md index 9f18ed08e..3de3bfaf3 100644 --- a/text/0374-jsii-modular.md +++ b/text/0374-jsii-modular.md @@ -173,8 +173,8 @@ well as from their consumers. Separating the mono-repository into multiple repositories will help ensure we maintain backwards compatibility between individual packages, and reduce the -risk of creating codependent packages (different repositories need to be -released independenlty, so dependencies can only flow in an asyclic manner). +risk of creating co-dependent packages (different repositories need to be +released independently, so dependencies can only flow in an acyclic manner). This will also make it easier for new contributors to approach *jsii*, as they will be able to focus strictly on one package, instead of having the entire constellation in their working set. From ac3b53ddb726ad81e363b223aeb7ab8222775f39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Tue, 3 May 2022 14:03:17 +0200 Subject: [PATCH 06/24] Re-frame the RFC to be only about the compiler version --- text/0374-jsii-modular.md | 287 -------------------------------- text/0374-jsii-ts-version.md | 307 +++++++++++++++++++++++++++++++++++ 2 files changed, 307 insertions(+), 287 deletions(-) delete mode 100644 text/0374-jsii-modular.md create mode 100644 text/0374-jsii-ts-version.md diff --git a/text/0374-jsii-modular.md b/text/0374-jsii-modular.md deleted file mode 100644 index 3de3bfaf3..000000000 --- a/text/0374-jsii-modular.md +++ /dev/null @@ -1,287 +0,0 @@ -# Modular jsii - -* **Original Author(s)**: @RomainMuller -* **Tracking Issue**: #374 -* **API Bar Raiser**: @{BAR_RAISER_USER} - -This RFC proposes to unlock (de-couple) the versions of all jsii packages -(i.e: compiler, code generators, runtimes, tools and libraries) in order to -enable introduction of new major versions of any of these packages without -necessarily incurring a new major version of all other packages. - -In order to make it easier to operate with de-coupled package versions, this RFC -further proposes we break the [aws/jsii](https://github.com/aws/jsii) mono-repo -into multiple single-package repositories. - -## Working Backwards - -### Release Notes entry - -```md -Future releases of the *jsii* package constellation will no longer follow an -all-at-once version increment strategy. Instead, each individual package will be -released under their own version line. It is hence no longer necessary to ensure -the version of all *jsii* packages in a product's dependency are aligned on the -exact same release. For example, it is now possible to have a dependency on the -`jsii` compiler at `4.3.0` while using `jsii-pacmak` at `1.35.0`, which -previously would have led to a fatal error when executing `jsii-pacmak`. - -BREAKING CHANGE: In order to allow developers to use the latest & greatest -features of TypeScript, the `jsii` compiler no longer follows semantic -versioning. Instead, releases are made in-line with those of the `typescript` -compiler, which does not follow semantic versioning. The TypeScript compiler -releases new language features (and often, syntax breaking changes) on each new -*major.minor* release. Future `jsii` releases will share the major and minor -version numbers with the `typescript` release they are built on (e.g: `jsii` -releases in the `4.3.x` line are built on top of series `4.3.x` of the -`typescript` compiler). -``` - -### `CONTRIBUTING` guides - -Each new repository will get a fresh `CONTRIBUTING.md` guide that includes the -following blurb (except for the repository for `@jsii/jsii-spec`): - -```md -This package is part of the *jsii* constellation. It is essential for this -package to consistently produce or consume `.jsii` assemblies according to the -specification defined by the [`@jsii/spec` package][@jsii/spec]. - -[@jsii/spec]: https://github.com/aws/jsii-spec -``` - -The `CONTRIBUTING.md` guide for the `@jsii/spec` package will have the following -blurb instead: - -```md -This package defines the shared interface between each package of the *jsii* -constellation. Changes made to this package must always be backwards compatible: -a new major version of `@jsii/spec` must retain the ability to correctly process -assemblies that were accepted by previous major versions. -``` - -### `README.md` for the `jsii` compiler - -````md -In order to allow developers to access and leverage the latest and greatest of -*TypeScript* language features, `jsii` compiler releases follow the `typescript` -package releases. For example, `jsii` version `4.3.x` is built on top of version -`4.3.x` of the `typescript` compiler. - -> IMPORTANT: As `typescript` package does not follow semantic versioning. -> Minor releases of the `typescript` compiler almost always include syntax -> breaking changes together with new language features. Since `jsii` now -> releases in line with `typescript` minor lines, `jsii` no longer adheres to -> semantic versioning. - -The `jsii` release notes for the initial release on each new *major.minor* line -will include a link to the corresponding TypeScript release notes entry, and a -description of any `jsii` breaking changes that may have been introduced with -the release. - -When setting up a `jsii` project, we recommend pinning the dependency on the -`jsii` compiler to the desired minor version line (which corresponds to the -`typescript` release line), using a `~` SemVer range: - -```js -{ - // ... - "devDependencies": { - // ... - "jsii": "~4.3.1", - // ... - }, - // ... -} -``` -```` - ---- - -Ticking the box below indicates that the public API of this RFC has been -signed-off by the API bar raiser (the `api-approved` label was applied to the -RFC pull request): - -``` -[ ] Signed-off by API Bar Raiser @xxxxx -``` - -## Public FAQ - -> This section should include answers to questions readers will likely ask about -> this release. Similar to the "working backwards", this section should be -> written in a language as if the feature is now released. -> -> The template includes a some common questions, feel free to add any questions -> that might be relevant to this feature or omit questions that you feel are not -> applicable. - -### What are we launching today? - -We are announcing a change in versioning strategy for the *jsii* constellation -of packages, which opens the way for an increased pace of innovation in the -*jsii* ecosystem: - -- Each package of the constellation now has it's own, independent version - number, and only gets a new release when a change was introduced; -- The `jsii` compiler now follows the `typescript` compiler version number, - allowing developers to easily leverage improvements in the *TypeScript* - language and compiler performance; -- The `@jsii/spec` package guarantees all releases of packages in the - constellation remain inter-operable going forward. - -### Why should I use this feature? - -The new versioning strategy allows developers to have greater control over the -*jsii* tools they use. It allows developers to benefit from improvements to the -*TypeScript* language (and compiler performance) faster, by allowing them to -upgrade their project on their own timeline - in the same way they would be able -to do for a "pure" *TypeScript* project. - -Since all parts of the *jsii* constellation are inter-operable with all major -releases of the *jsii* packages, developers are able to opt into new and -improved code-generation features of `jsii-pacmak` on their own schedule (i.e: -when they release a new major version of their library) without requiring all -their dependencies and dependents use the same version of `jsii-pacmak`. - -## Internal FAQ - -### Why are we doing this? - -We are doing this to reduce the friction involved in making major changes to any -of the *jsii* constellation of packages. This will allow breaking changes to be -introduced in parts of the ecosystem without bumping the major version of the -rest of packages. - -In particular, it is currently difficult to introduce breaking changes to the -compiler (such as: moving to a more recent version of TypeScript, adding new -compile-time validations that break existing code, removing behaviors such as -the peer dependencies update which are no longer desirable, dropping support for -older runtime versions, etc...), as bumping the major version of all packages -implies fragmenting the entire ecosystem (between what's been upgraded, and what -has not been upgraded). - -This will improve our pace of innovation, as we will hence be able to introduce -a new major version of any part of the ecosystem wihtout necessarily requiring -all downstream consumers to migrate all at once. - -For example, this allows the `jsii` compiler to be upgraded to a new release -line of `typescript` without forcing every downstream consumer to also accept -the syntax breaking changes at the same time. Instead, consumers will be free -to take on a new release line of `jsii` independently from their dependencies as -well as from their consumers. - -Separating the mono-repository into multiple repositories will help ensure we -maintain backwards compatibility between individual packages, and reduce the -risk of creating co-dependent packages (different repositories need to be -released independently, so dependencies can only flow in an acyclic manner). -This will also make it easier for new contributors to approach *jsii*, as they -will be able to focus strictly on one package, instead of having the entire -constellation in their working set. - -### Why should we _not_ do this? - -Breaking up the mono-repository into multiple independent repositories will come -at a higher maintenance cost than having a single repository. The act of moving -code around will also require some time to be invested: there are currently -co-dependent relationships between certain packages (`jsii-pacmak` has a local -develooment dependency on the runtimes, and on the `jsii-calc` packages, etc...) -that will need to be broken. Additionally, some checks currently enforce that -all tools used to work on an assembly are on the same version line, which will -no longer be the case. - -### What is the technical solution (design) of this feature? - -The first component of implementing this RFC is to migrate code for various -tools and libraries to their own repository: - -- `@jsii/spec` and `jsii-reflect` (those can be combined as they have similar - purpose) -- `jsii` -- `jsii-pacmak` -- `jsii-rosetta` -- `@jsii/kernel` and `@jsii/runtime` (which could be combined into a single - package) -- Each individual `@jsii/*-runtime` package (and related tests) - -Those new repositories could be created within the `aws` GitHub organization, or -alternatively a new organization could be created (the `jsii` name is already in -use as a GitHub organization). - -The second component of this RFC is changing the release strategy for the `jsii` -compiler so that it follows `typescript` version lines (`major.minor`), and -ensuring other downstream consumers of `.jsii` assemblies do not attempt to -enforce version consistency using the `jsiiVersion` field. - -### Is this a breaking change? - -This is not a breaking change in the traditional sense: all existing code will -continue to work with the current release lines of all packages in the -ecosystem. However, the new versioning strategy of `jsii` is a departure from -Semantic Versioning, which will be accompanied with a major version change (from -`1.x` to `4.3.x` - matching the current `typescript` release line). This is to -be noted in the release ntoes. - -### What alternative solutions did you consider? - -#### Bring-your-own TypeScript version - -One of the main rationales for this change is to enable the use of new -TypeScript releases without forcing the enitre package ecosystem to make the -change at the same time (due to language-breaking changes). - -An option to address this would be to allow customers to "bring their own" -TypeScript compiler, by making it a `peerDependency`. This however comes with -two main challenges: - -- The TypeScript compiler API is not stable between TypeScript releases, and it - is hence not possible to author a `jsii` compiler that can leverage an - arbitrary TypeScript version. -- Declarations files emitted by different TypeScript compiler versions may not - be compatible with previous versions of TypeScript. Addressing this particular - issue would require all customers use a tool such as `downlevel-dts` to - produce declarations files compatible with previous iterations of TypeScript. - The `jsii` compiler is a better place to address this. - -#### Coordinating major versions with root consumers - -An alternative to de-coupled versioning is to time breaking changes in the -*jsii* constellation with new major releases of the root consumer libraries -(`constructs`, `aws-cdk-lib`, ...), however this forgets to account for the -existence of other consumers of *jsii* which do not depend on these libraries, -and may hence not have the same drive to release a new major version at that -time. Additionally, such major releases are expected to be infrequent as they -represent a major burden on the community, meaning our ability to release -improvements to *jsii* packages would be severely limited. - -#### Unlock versions, but keep mono-repository - -It would also be possible to unlock versions in the mono-repository, in order to -allow each packages to include breaking changes when necessary. However, this -makes it all too easy to inadvertently break backwards compatibility, as it is -so tempting to introduce the fix for a breaking change in the same PR as the -breaking change itself. Using several repositories makes this much less likely. - -### What are the drawbacks of this solution? - -This solution will increase the number of repositories that have to be monitored -for issues and feature requests, as well as for new contributions from members -of the community. - -It might also make the project as a whole more difficult to navigate, as it will -be spread over multiple packages, instead of being in a centralized location. - -### What is the high-level project plan? - -1. Determine the new repository naming scheme (which GitHub organization do we - use to host the repositories, what is the exact partition plan) -1. Extract the code for the `jsii` compiler, and start releasing with a - `major.minor` matching those of the underlying `typescript` release -1. Extract the code for the `jsii-pacmak` tool -1. Extract the code for the `@jsii/runtime` and `@jsii/kernel` packages -1. Extract the code for each `@jsii/*-runtime` package -1. Extract the remaining tools - -### Are there any open issues that need to be addressed later? - -- What GitHub organzaition or naming scheme will be used for these? diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md new file mode 100644 index 000000000..208e14649 --- /dev/null +++ b/text/0374-jsii-ts-version.md @@ -0,0 +1,307 @@ +# The jsii compiler to follow TypeScript versioning + +* **Original Author(s)**: @RomainMuller +* **Tracking Issue**: #374 +* **API Bar Raiser**: @{BAR_RAISER_USER} + +This RFC proposes to change the versioning scheme of the `jsii` compiler to stop +conforming to [semantic versioning][semver], and instead use the `major.minor` +version of the [TypeScript] compiler it is built on. + +## Working Backwards + +### Release Notes entry + +```md +Starting with this release, the `jsii` compiler will no longer conform to +[semantic versioning][semver]. Instead, its `major.minor` version will match +that of the [TypeScript] compiler it uses (the [TypeScript] compiler does not +conform to [semantic versioning][semver]). + +This change is made to allow developers to benefit from the latest and greatest +features of the [TypeScript] language without requiring the entire ecosystem to +make the switch at the same time. + +BREAKING CHANGE: In order to allow developers to use the latest & greatest +features of TypeScript, the `jsii` compiler no longer follows semantic +versioning. Instead, releases are made in-line with those of the `typescript` +compiler, which does not follow semantic versioning. We recommend you upgrade +your `devDependency` on `jsii` to use a tilde range (e.g: `~4.7.0`) to be able +to control when you migrate to future [TypeScript] language versions. +``` + +### `README.md` for the `jsii` compiler + +````md +In order to allow developers to access and leverage the latest and greatest of +*TypeScript* language features, `jsii` compiler releases follow the `typescript` +package releases. For example, `jsii` version `4.3.x` is built on top of version +`4.3.x` of the `typescript` compiler. + +> IMPORTANT: As `typescript` package does not follow semantic versioning. +> Minor releases of the `typescript` compiler almost always include syntax +> breaking changes together with new language features. Since `jsii` releases in +> line with `typescript` minor lines, `jsii` does not adhere to semantic +> versioning either. + +The `jsii` release notes for the initial release on each new *major.minor* line +will include a link to the corresponding TypeScript release notes entry, and a +description of any `jsii` breaking changes that may have been introduced with +the release. + +When setting up a `jsii` project, we recommend pinning the dependency on the +`jsii` compiler to the desired minor version line (which corresponds to the +`typescript` release line), using a `~` SemVer range: + +```js +{ + // ... + "devDependencies": { + // ... + "jsii": "~4.7.0", + // ... + }, + // ... +} +``` +```` + +--- + +Ticking the box below indicates that the public API of this RFC has been +signed-off by the API bar raiser (the `api-approved` label was applied to the +RFC pull request): + +``` +[ ] Signed-off by API Bar Raiser @xxxxx +``` + +## Public FAQ + +> This section should include answers to questions readers will likely ask about +> this release. Similar to the "working backwards", this section should be +> written in a language as if the feature is now released. +> +> The template includes a some common questions, feel free to add any questions +> that might be relevant to this feature or omit questions that you feel are not +> applicable. + +### What are we launching today? + +We are announcing a change in versioning strategy for the `jsii` compiler. +Starting today, new releases of the `jsii` package will use the same +`major.minor` version as the [TypeScript] compiler it is built on. + +Since the [TypeScript] compiler does not conform to [SemVer], future releases of +the `jsii` compiler will not conform to [SemVer] either. In line with the +[TypeScript] compiler versioning scheme, breaking changes may be introduced in +any new release that updates the `major` or `minor` version, but **not** when +only the `patch` level changed. + +This change enables `jsii` users to benefit from the latest and greatest +features introduced in the [TypeScript] language as well as from performance +improvements and bug fixes introduced in recent versions of [TypeScript], +without requiring the entire ecosystem to update compiler versions at the same +time. + +### Why should I use this feature? + +The new `jsii` versioning strategy gives developers more control over the +[TypeScript] language version they are developing, without forcing an update +schedule on them. + +Developers are free to decide when it is appropriate for them to upgrade their +`jsii` dependency to a new `major.minor` version line, bringing in new +[TypeScript] language features as well as performance improvements and bug +fixes. + +The `jsii` compiler makes the due dilligence to ensure the artifacts produced +(in particular, the `.d.ts` declarations files and the `.jsii` assemblies) +remain compatible with previous versions, so that consumers of libraries need +not update at the same time as their dependencies. + +### What happens to `jsii` v1? + +Version `1.0.0` of the `jsii` compiler was released over two years ago (in +February 2020), and will transition to the *Maintenance* tier of the +[AWS SDKs and Tools maintenance policy][aws-policy] 6 months after this release. + +During this initial 6 months period, `jsii` will continue to receive full +support, including bug fixes and feature support, as it has in the past two +years. + +Once it enters the *Maintenance* tier, it will only receive fixes for critical +bugs and security issues. The `v1` release line will remain in *Maintenace* for +12 months, after which it will transition into the *End-of-Life* tier. + +### What is the support policy for these new releases? + +Starting with release `4.7.0`, new features will only be added to the *current* +release line (the *latest* `major.minor` stream), which corresponds to the +currently active [TypeScript] release line. + +Critical bug fixes and security patches will be provided for previous release +lines for 12 months, which covers 3 or 4 previous lines. Features will not be +back-ported to non-current release lines. + +Previous release lines will be considered *end-of-life* 12 months after they +were superceded by a new *current* line. + +## Internal FAQ + +### Why are we doing this? + +Before this change, `jsii` users had been stuck with [TypeScript] `3.9` for a +very long time, due to the introduction of several breaking changes in the +language specification: upgrading the [TypeScript] compiler that `jsii` builds +on would cause existing code to break. + +This could not be addressed by issuing a new major release of `jsii`, as this +would cause the ecosystem to be fragmented between packages that have migrated +to the new major release, and those that haven't. Additionally, a package could +only migrate if all of their dependencies are already using the new `jsii` major +release, and they'd likely need to also release a new major version as a +consequence. + +In order to allow each package author to decide for themselves without hinging +on their dependencie's choices, or influencing their dependents, we are making +it possible for every developer to decide when they want to migrate to a new +version of the [TypeScript] language, by following [TypeScript]'s versioning for +the compiler, and continuing to perform coordinated releases of every other +package in the toolchain. + +### Why should we _not_ do this? + +[Semantic versioning][semver] is the dominant versioning scheme in the +JavaScript world, and diverging from it might break assumptions customers make +when consuming packages from [npm](npmjs.com). + +Following [TypeScript] versions means releasing new `major.minor` releases (that +may include breaking changes) more often than is currently done (the +[TypeScript] maintainers typically declare a new `major.minor` line four +times per year: in February, May, August and November respectively). This is a +lot more release lines than other AWS products offer, and it would not be +reasonable to uphold the [AWS SDKs and Tools maintenance policy][aws-policy], +as it requires offering full support (features and bug fixes) for "Generally +Available" releases for a minimum of 24 months. Diverging from this +[policy][aws-policy] is a significant change that customers may not expect. + +### What is the technical solution (design) of this feature? + +The proposed delivery plan for this feature is as follows: + +* Communicate about the upcoming change in new releases on the `v1` release + line, including a planned timeline for the initial release of the `v4.7` line, + and language about the departure from [SemVer]. + +* **Optional:** Separate the `jsii` compiler from the rest of packages in the + jsii toolchain into separate repositories. This would make it easier to + release the `jsii` compiler separately from other parts of the toolchain that + follow a different versioning scheme. + + - Move other packages to a new mono-repository (or to several new individual + package repositories), e.g: `github.com/aws/jsii-toolchain`. + + - Make the `github.com/aws/jsii` repository by a single-package repository. + +* Update the *release* automation to use the [TypeScript] compiler version's + `major.minor` level, and only update the `patch` level on new releases. + +* Upgrade the [TypeScript] compiler internally used by `jsii` to the current + `latest` release of the `typescript` package. + +* Make the `jsii` compiler transparently prepare down-leveled declarations files + to ensure backwards-compatibility of compiler outputs with previous releases + of `jsii`. This can be done using the [`downlevel-dts`][downlevel-dts] package + to produce declarations files compatible with [TypeScript] `3.9`, and adding + a `typesVersions` key to the `package.json` file of packages. + + - See proof-of-concept: [`aws/jsii#3501`][aws/jsii-3501] + +* Release the initial `jsii` release on the `4.7` line. + +* Formally announce that the `v1` release line of `jsii` will move into the + *Maintenance* tier of the [AWS SDKs and Tools maintenance policy][aws-policy] + in 6 months, and explain the policy that is applicable to newer releases. + +* **6 months later:** Formally announce that the `v1` release line of `jsii` is + entering the *Maintenance* tier of the [AWS SDKs and Tools maintenance + policy][aws-policy], and will continue to receive critical bug and security + fixes for 12 months before transitioning to *end-of-life*, and repeat the + maintenance policy that new releases will benefit from. + +* **12 months later:** Formally announce that the `v1` release line of `jsii` is + transitioning to *end-of-life* and will no longer receive any updates. Repeat + the maintenance policy that is applicable to newer releases. + +### Is this a breaking change? + +This is not a breaking change in the traditional sense, however this is a +significant change in versioning schemes used for the `jsii` compiler, and a +departure from the [AWS SDKs and Tools maintenance policy][aws-policy]. + +As such, this warrants ample communication with our customer base to avoid they +are caught by surprise, or have broken expectations. + +### What alternative solutions did you consider? + +#### Bring-your-own TypeScript version + +One of the main rationales for this change is to enable the use of new +TypeScript releases without forcing the enitre package ecosystem to make the +change at the same time (due to language-breaking changes). + +An option to address this would be to allow customers to "bring their own" +TypeScript compiler, by making it a `peerDependency`. This however comes with +a significant challenge: the TypeScript compiler API is not stable between +TypeScript releases, and it is hence not possible to author a `jsii` compiler +that can leverage an arbitrary TypeScript version. + +#### Only de-couple the `jsii` package version, but stick with [SemVer] + +It would technically be possible to de-couple the `jsii` package from the rest +of the toolchain's versioning, and to issue a new `jsii` major version each time +we update the [TypeScript] compiler it internally uses. This would however make +it difficult for customers to understand the relationship between `jsii` major +releases and the [TypeScript] language level they support. + +Using the same version number prefix (`major.minor`) as the [TypeScript] +compiler makes the relationship clear and removes the need to maintain separate +documentation for customers to understand what they are upgrading to. + +### What are the drawbacks of this solution? + +This solution is a stark departure from versioning schemes and maintenance +policies used by AWS on open-source products. It implies offering critical bug +fixes and security updates for up to 5 different release lines (1 current, and +3 to 4 previous), which might require significant effort. + +Following the [TypeScript] `major.minor` reduces our ability to introduce +breaking changes to the `jsii` compiler, as these must be timed together with +[TypeScript] `major.minor` release timelines. However, since [TypeScript] +releases a new `major.minor` line 4 times a year, this is not a blocker, but +will require careful planning. + +### What is the high-level project plan? + +Item | Estimation | Notes +------------------------------------------|------------|-------- +Initial communication | 1 day | +**Optional:** Break mono-repository out | 5 days | +Have `jsii` down-level `.d.ts` | 5 days | [`aws/jsii#3501`][aws/jsii-3501] +Update release automation | 2 days | +Update [TypeScript] dependency | 5 days | +Initial Release | 1 day | +Maintenance Announcement | 1 day | +Move to Maintenance | 1 day | +Move to end-of-life | 1 day | + +### Are there any open issues that need to be addressed later? + + + +[semver]: https://semver.org/spec/v2.0.0.html +[TypeScript]: https://www.typescriptlang.org +[aws-policy]: https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html +[downlevel-dts]: https://www.npmjs.com/package/downlevel-dts +[aws/jsii-3501]: https://github.com/aws/jsii/pull/3501 From 942cedb14fe2bc23bb40a1a70704c9afd060bb7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Tue, 3 May 2022 14:10:50 +0200 Subject: [PATCH 07/24] Add explanations about backwards compatibility --- text/0374-jsii-ts-version.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 208e14649..42372bbf1 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -149,6 +149,23 @@ were superceded by a new *current* line. ## Internal FAQ +### How will we maintain backwards compatibility? + +The change only affects the [TypeScript] compiler version used internally by +`jsii` and the versioning scheme for the `jsii` package itself. + +The compiler will continue to emit `.jsii` assemblies that conform to the schema +defined in the `@jsii/spec` package, which will hence continue to be compatible +with all other tools part of the jsii toolchain (including `jsii-pacmak`, ...). + +In order to maximize compatibility between [TypeScript] compiler versions, and +since [TypeScript] occasionally introduces backwards-incompatible syntax changes +(additions, modifications) to the declarations files (`.d.ts`), the `jsii` +compiler will proactively produce down-leveled declarations files targeting +[TypeScript] compiler versions used by previous (not yet *end-of-life*) releases +of `jsii`. This can be achieved using the [`downlevel-dts`][downlevel-dts] +utility. + ### Why are we doing this? Before this change, `jsii` users had been stuck with [TypeScript] `3.9` for a From 7457ce8c31d93e6eea45369c18941ea354863191 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Wed, 11 May 2022 15:29:40 +0200 Subject: [PATCH 08/24] Add wording about the difficulty of re-exporting ts --- text/0374-jsii-ts-version.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 42372bbf1..eacff4070 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -271,8 +271,12 @@ change at the same time (due to language-breaking changes). An option to address this would be to allow customers to "bring their own" TypeScript compiler, by making it a `peerDependency`. This however comes with a significant challenge: the TypeScript compiler API is not stable between -TypeScript releases, and it is hence not possible to author a `jsii` compiler -that can leverage an arbitrary TypeScript version. +TypeScript releases. Addressing this would require maintaining an adapter layer +for each supported version of the TypeScript compiler, and this would require +tremendous efforts, in particular as there appears to be no way in TypeScript +to re-export a `namespace` including all the type declarations it contains, as +`typeof ts` (assuming `ts` is the TypeScript compiler namespace) only represents +entities with a run-time value, and none of the interfaces it contains. #### Only de-couple the `jsii` package version, but stick with [SemVer] From 3ca0ee0d29accfafe906ef7a834021ab7a0f834a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Fri, 3 Jun 2022 11:56:23 +0200 Subject: [PATCH 09/24] Addressed feedback --- text/0374-jsii-ts-version.md | 174 ++++++++++++++++++++++++++++------- 1 file changed, 142 insertions(+), 32 deletions(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index eacff4070..26450e89c 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -1,33 +1,48 @@ -# The jsii compiler to follow TypeScript versioning +# The `jsii` compiler (and `jsii-rosetta`) to follow TypeScript versioning * **Original Author(s)**: @RomainMuller * **Tracking Issue**: #374 * **API Bar Raiser**: @{BAR_RAISER_USER} -This RFC proposes to change the versioning scheme of the `jsii` compiler to stop -conforming to [semantic versioning][semver], and instead use the `major.minor` -version of the [TypeScript] compiler it is built on. +This RFC proposes to change the versioning scheme of the `jsii` compiler and +`jsii-rosetta` to stop conforming to [semantic versioning][semver], and instead +use the `major.minor` version of the [TypeScript] compiler it is built on. + +Other packages (such as `jsii-pacmak`, `@jsii/spec`, ...) are not affected by +this proposal and will continue to conform to [semantic versioning][semver]. ## Working Backwards ### Release Notes entry ```md -Starting with this release, the `jsii` compiler will no longer conform to -[semantic versioning][semver]. Instead, its `major.minor` version will match -that of the [TypeScript] compiler it uses (the [TypeScript] compiler does not -conform to [semantic versioning][semver]). +Starting with this release, the `jsii` compiler and `jsii-rosetta` will no +longer conform to [semantic versioning][semver]. Instead, its `major.minor` +version will match that of the [TypeScript] compiler it uses (the [TypeScript] +compiler does not conform to [semantic versioning][semver]). New features will +only be introduced on the `jsii` release line that targets the latest +[TypeScript] compiler. + +Users may need to modify they code when upgrading from one `major.minor` release +line to another (addressing [TypeScript] language evolutions and `jsii` feature +evolutions). While upgrading to the latest release line of `jsii` helps minimize +the effort required for these updates, the release strategy allows developers to +do so on their own schedule. This change is made to allow developers to benefit from the latest and greatest features of the [TypeScript] language without requiring the entire ecosystem to make the switch at the same time. +Other packages in the jsii toolchain (such as `jsii-pacmak`, `@jsii/spec`, and +others) are not affected by this change and will continue to follow [semantic +versioning][semver] as they currently do. + BREAKING CHANGE: In order to allow developers to use the latest & greatest -features of TypeScript, the `jsii` compiler no longer follows semantic -versioning. Instead, releases are made in-line with those of the `typescript` -compiler, which does not follow semantic versioning. We recommend you upgrade -your `devDependency` on `jsii` to use a tilde range (e.g: `~4.7.0`) to be able -to control when you migrate to future [TypeScript] language versions. +features of TypeScript, the `jsii` compiler and `jsii-rosetta` no longer follow +semantic versioning. Instead, releases are made in-line with those of the +`typescript` compiler, which does not follow semantic versioning. We recommend +you upgrade your `devDependency` on `jsii` to use a tilde range (e.g: `~4.7.0`) +to be able to control when you migrate to future [TypeScript] language versions. ``` ### `README.md` for the `jsii` compiler @@ -66,6 +81,42 @@ When setting up a `jsii` project, we recommend pinning the dependency on the ``` ```` +### `README.md` for the `jsii-rosetta` package + +````md +In order to allow developers to access and leverage the latest and greatest of +*TypeScript* language features, `jsii-rosetta` releases follow the `typescript` +package releases. For example, `jsii-rosetta` version `4.3.x` is built on top of +version `4.3.x` of the `typescript` compiler. + +> IMPORTANT: As `typescript` package does not follow semantic versioning. +> Minor releases of the `typescript` compiler almost always include syntax +> breaking changes together with new language features. Since `jsii-rosetta` +> releases in line with `typescript` minor lines, `jsii-rosetta` does not adhere +> to semantic versioning either. + +The `jsii-rosetta` release notes for the initial release on each new +*major.minor* line will include a link to the corresponding TypeScript release +notes entry, and a description of any `jsii` breaking changes that may have been +introduced with the release. + +When using `jsii-rosetta` in a project, we recommend pinning the dependency on +`jsii-rosetta` to the desired minor version line (which corresponds to the +`typescript` release line), using a `~` SemVer range: + +```js +{ + // ... + "devDependencies": { + // ... + "jsii-rosetta": "~4.7.0", + // ... + }, + // ... +} +``` +```` + --- Ticking the box below indicates that the public API of this RFC has been @@ -88,9 +139,11 @@ RFC pull request): ### What are we launching today? -We are announcing a change in versioning strategy for the `jsii` compiler. -Starting today, new releases of the `jsii` package will use the same -`major.minor` version as the [TypeScript] compiler it is built on. +We are announcing a change in versioning strategy for the `jsii` compiler and +`jsii-rosetta`. Starting today, new releases of the `jsii` and `jsii-rosetta` +packages will use the same `major.minor` version as the [TypeScript] compiler +they are built on. Other packages in the jsii toolchain (`jsii-pacmak`, +`@jsii/spec`, ...) are unaffected by this change. Since the [TypeScript] compiler does not conform to [SemVer], future releases of the `jsii` compiler will not conform to [SemVer] either. In line with the @@ -115,6 +168,8 @@ Developers are free to decide when it is appropriate for them to upgrade their [TypeScript] language features as well as performance improvements and bug fixes. +### Do I need to use the same `jsii` version as my dependencies? + The `jsii` compiler makes the due dilligence to ensure the artifacts produced (in particular, the `.d.ts` declarations files and the `.jsii` assemblies) remain compatible with previous versions, so that consumers of libraries need @@ -151,8 +206,8 @@ were superceded by a new *current* line. ### How will we maintain backwards compatibility? -The change only affects the [TypeScript] compiler version used internally by -`jsii` and the versioning scheme for the `jsii` package itself. +The change only affects the [TypeScript] compiler version used internally by the +`jsii` compiler and the versioning scheme for the `jsii` package itself. The compiler will continue to emit `.jsii` assemblies that conform to the schema defined in the `@jsii/spec` package, which will hence continue to be compatible @@ -164,7 +219,10 @@ since [TypeScript] occasionally introduces backwards-incompatible syntax changes compiler will proactively produce down-leveled declarations files targeting [TypeScript] compiler versions used by previous (not yet *end-of-life*) releases of `jsii`. This can be achieved using the [`downlevel-dts`][downlevel-dts] -utility. +utility. Failure to do so may make it impossible to use a library compiled with +a given release of `jsii` in a project that is still using an older release, +which would be akin to forcing dependents to upgrade at the same pace as their +dependencies (which is undersiable). ### Why are we doing this? @@ -173,19 +231,23 @@ very long time, due to the introduction of several breaking changes in the language specification: upgrading the [TypeScript] compiler that `jsii` builds on would cause existing code to break. -This could not be addressed by issuing a new major release of `jsii`, as this -would cause the ecosystem to be fragmented between packages that have migrated -to the new major release, and those that haven't. Additionally, a package could -only migrate if all of their dependencies are already using the new `jsii` major -release, and they'd likely need to also release a new major version as a -consequence. - In order to allow each package author to decide for themselves without hinging -on their dependencie's choices, or influencing their dependents, we are making +on their dependencies' choices, or influencing their dependents, we are making it possible for every developer to decide when they want to migrate to a new version of the [TypeScript] language, by following [TypeScript]'s versioning for the compiler, and continuing to perform coordinated releases of every other -package in the toolchain. +package in the toolchain (those are unaffected by this change). + +The `jsii-rosetta` package also internally uses the [TypeScript] compiler that +needs to be compatible with the [TypeScript] language level used by the project. +Developers hence need to also be able to control which [TypeScript] version is +being used by `jsii-rosetta` if they want to use this. + +Using the same `major.minor` version as the [TypeScript] compiler makes it easy +for developers to identify which [TypeScript] language features are available to +them or not. As the [TypeScript] compiler does not conform to [semantic +versioning][semver], this implies `jsii` and `jsii-rosetta` also need to stop +conforming to it. ### Why should we _not_ do this? @@ -200,8 +262,11 @@ times per year: in February, May, August and November respectively). This is a lot more release lines than other AWS products offer, and it would not be reasonable to uphold the [AWS SDKs and Tools maintenance policy][aws-policy], as it requires offering full support (features and bug fixes) for "Generally -Available" releases for a minimum of 24 months. Diverging from this -[policy][aws-policy] is a significant change that customers may not expect. +Available" releases for a minimum of 24 months (this would require providing +full support for 8 different releases, and back-porting automation is likely to +be difficult due to the amount of breaking changes in the [TypeScript] compiler +API between releases). Diverging from this [policy][aws-policy] is a significant +change that customers may not expect. ### What is the technical solution (design) of this feature? @@ -235,7 +300,9 @@ The proposed delivery plan for this feature is as follows: - See proof-of-concept: [`aws/jsii#3501`][aws/jsii-3501] -* Release the initial `jsii` release on the `4.7` line. +* Release the initial `jsii` release on the `4.7` line (for practical reasons, + we will disregard [TypeScript] releases between `3.9` and the _current_ + version when this proposal is implemented, which at time of writing is `4.7`). * Formally announce that the `v1` release line of `jsii` will move into the *Maintenance* tier of the [AWS SDKs and Tools maintenance policy][aws-policy] @@ -276,7 +343,11 @@ for each supported version of the TypeScript compiler, and this would require tremendous efforts, in particular as there appears to be no way in TypeScript to re-export a `namespace` including all the type declarations it contains, as `typeof ts` (assuming `ts` is the TypeScript compiler namespace) only represents -entities with a run-time value, and none of the interfaces it contains. +entities with a run-time value, and none of the interfaces it contains. The +consequence of this is that writing an adapter for a particular [TypeScript] +version requires wrapping all useful functions of the compiler API and +re-delcaring the types they use, which represents hundreds if not thousands of +lines of code for each supported version. #### Only de-couple the `jsii` package version, but stick with [SemVer] @@ -290,6 +361,25 @@ Using the same version number prefix (`major.minor`) as the [TypeScript] compiler makes the relationship clear and removes the need to maintain separate documentation for customers to understand what they are upgrading to. +#### Release a different package for each supported [TypeScript] version + +The release model used by `cdk8s-plus` involves releasing a different package +for each version of the underlying resources (e.g: `cdk8s-plus-22` targets +version 22 of the resources). A similar model could be used for `jsii`, where a +package named `jsii-4.7` could be released for the compiler that builds on +[TypeScript] `4.7.x`. + +This release pattern however creates an opportunity for supply-chain attacks as +a malicious party could release `jsii-4.10` ahead of us and possibly exploit +unsuspecting users. + +The attack vector can be mitigated by scoping the packages since npm scopes +provide ownership guarantees, which would require releasing +`@jsii/typescript-4.7`. However this approach makes it more difficult for +customers to know when a new release of the compiler is available, since +dependency maintenance automation will only look for new versions of the same +package. + ### What are the drawbacks of this solution? This solution is a stark departure from versioning schemes and maintenance @@ -303,6 +393,21 @@ breaking changes to the `jsii` compiler, as these must be timed together with releases a new `major.minor` line 4 times a year, this is not a blocker, but will require careful planning. +Breaking changes that could be tempting to introduce in new `major.minor` +release lines include: + +- Upgrading default severity of some diagnostic messages to `ERROR` +- Adding new compile-time validations +- Dropping support for a recently end-of-life `node` version (this happens once + or twice a year) +- Dropping support for a particular TypeScript language version (for example, + [DefinitelyTyped] packages only support TypeScript compilers that are less + than 2 years old) +- Changing configuration file syntax, format, default values or required entries +- Addressing a security issue that requires breaking existing code + +[DefinitelyTyped]: https://github.com/DefinitelyTyped/DefinitelyTyped#support-window + ### What is the high-level project plan? Item | Estimation | Notes @@ -311,8 +416,13 @@ Initial communication | 1 day | **Optional:** Break mono-repository out | 5 days | Have `jsii` down-level `.d.ts` | 5 days | [`aws/jsii#3501`][aws/jsii-3501] Update release automation | 2 days | +Update contributor guide | 1 day | +Update jsii documentation | 2 days | Update [TypeScript] dependency | 5 days | Initial Release | 1 day | +Update `projen`'s `JsiiProject` defaults | 1 day | +Migrate `aws-cdk` to new `jsii` release | 10 days | Via a pre-release +Validate ConstructHub support | 3 days | Maintenance Announcement | 1 day | Move to Maintenance | 1 day | Move to end-of-life | 1 day | From 857d5385a56a01ffb69654d47380f9ba5d3643d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Wed, 21 Sep 2022 10:35:31 +0200 Subject: [PATCH 10/24] chore: make linter pass --- text/0374-jsii-ts-version.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 26450e89c..8efbaea53 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -2,7 +2,6 @@ * **Original Author(s)**: @RomainMuller * **Tracking Issue**: #374 -* **API Bar Raiser**: @{BAR_RAISER_USER} This RFC proposes to change the versioning scheme of the `jsii` compiler and `jsii-rosetta` to stop conforming to [semantic versioning][semver], and instead @@ -53,7 +52,7 @@ In order to allow developers to access and leverage the latest and greatest of package releases. For example, `jsii` version `4.3.x` is built on top of version `4.3.x` of the `typescript` compiler. -> IMPORTANT: As `typescript` package does not follow semantic versioning. +> IMPORTANT: The `typescript` package does not follow semantic versioning. > Minor releases of the `typescript` compiler almost always include syntax > breaking changes together with new language features. Since `jsii` releases in > line with `typescript` minor lines, `jsii` does not adhere to semantic @@ -89,7 +88,7 @@ In order to allow developers to access and leverage the latest and greatest of package releases. For example, `jsii-rosetta` version `4.3.x` is built on top of version `4.3.x` of the `typescript` compiler. -> IMPORTANT: As `typescript` package does not follow semantic versioning. +> IMPORTANT: The `typescript` package does not follow semantic versioning. > Minor releases of the `typescript` compiler almost always include syntax > breaking changes together with new language features. Since `jsii-rosetta` > releases in line with `typescript` minor lines, `jsii-rosetta` does not adhere @@ -117,16 +116,6 @@ When using `jsii-rosetta` in a project, we recommend pinning the dependency on ``` ```` ---- - -Ticking the box below indicates that the public API of this RFC has been -signed-off by the API bar raiser (the `api-approved` label was applied to the -RFC pull request): - -``` -[ ] Signed-off by API Bar Raiser @xxxxx -``` - ## Public FAQ > This section should include answers to questions readers will likely ask about @@ -429,8 +418,6 @@ Move to end-of-life | 1 day | ### Are there any open issues that need to be addressed later? - - [semver]: https://semver.org/spec/v2.0.0.html [TypeScript]: https://www.typescriptlang.org [aws-policy]: https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html From db308f9860aecabfa19e871cae107a07bb1cb0db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Wed, 21 Sep 2022 10:49:42 +0200 Subject: [PATCH 11/24] add blurb about new features --- text/0374-jsii-ts-version.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 8efbaea53..429e8f6ad 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -52,6 +52,11 @@ In order to allow developers to access and leverage the latest and greatest of package releases. For example, `jsii` version `4.3.x` is built on top of version `4.3.x` of the `typescript` compiler. +Going forward, new `jsii` compiler features will only be introduced in the +_latest_ available release line (corresponding to the latest TypeScript +version), while older release lines will only receive bug fixes until they reach +end-of-life. + > IMPORTANT: The `typescript` package does not follow semantic versioning. > Minor releases of the `typescript` compiler almost always include syntax > breaking changes together with new language features. Since `jsii` releases in @@ -88,6 +93,11 @@ In order to allow developers to access and leverage the latest and greatest of package releases. For example, `jsii-rosetta` version `4.3.x` is built on top of version `4.3.x` of the `typescript` compiler. +Going forward, new `jsii-rosetta` features will only be introduced in the +_latest_ available release line (corresponding to the latest TypeScript +version), while older release lines will only receive bug fixes until they reach +end-of-life. + > IMPORTANT: The `typescript` package does not follow semantic versioning. > Minor releases of the `typescript` compiler almost always include syntax > breaking changes together with new language features. Since `jsii-rosetta` From b66841c1264345754a3cf0a73766b8dd80dd97c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Wed, 21 Sep 2022 10:50:53 +0200 Subject: [PATCH 12/24] increase time estimate for upgrading TypeScript (the gap is broad) --- text/0374-jsii-ts-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 429e8f6ad..747ff83bf 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -417,7 +417,7 @@ Have `jsii` down-level `.d.ts` | 5 days | [`aws/jsii#3501`][aws/j Update release automation | 2 days | Update contributor guide | 1 day | Update jsii documentation | 2 days | -Update [TypeScript] dependency | 5 days | +Update [TypeScript] dependency | 15 days | Initial Release | 1 day | Update `projen`'s `JsiiProject` defaults | 1 day | Migrate `aws-cdk` to new `jsii` release | 10 days | Via a pre-release From 2cac75281ea42a22d7ee190047c748b62a294f15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Wed, 21 Sep 2022 11:38:32 +0200 Subject: [PATCH 13/24] Add mermaid gantt to illustrate support policy --- text/0374-jsii-ts-version.md | 73 +++++++++++++++++++++++++++++++++++- 1 file changed, 71 insertions(+), 2 deletions(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 747ff83bf..1377ff33a 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -8,7 +8,10 @@ This RFC proposes to change the versioning scheme of the `jsii` compiler and use the `major.minor` version of the [TypeScript] compiler it is built on. Other packages (such as `jsii-pacmak`, `@jsii/spec`, ...) are not affected by -this proposal and will continue to conform to [semantic versioning][semver]. +this proposal and will continue to conform to [semantic versioning][semver]. In +particular, code generated by `jsii-pamcak` will continue to use the `1.x` +release line of `@jsii/kernel`, `@jsii/runtime`, and the languages' runtime +libraries, so as to remain completely backwards compatible. ## Working Backwards @@ -34,7 +37,9 @@ make the switch at the same time. Other packages in the jsii toolchain (such as `jsii-pacmak`, `@jsii/spec`, and others) are not affected by this change and will continue to follow [semantic -versioning][semver] as they currently do. +versioning][semver] as they currently do. The bindings generated by +`jsii-pacmak` will also remain backwards compatible, as code generation is not +impacted by this change in any way. BREAKING CHANGE: In order to allow developers to use the latest & greatest features of TypeScript, the `jsii` compiler and `jsii-rosetta` no longer follow @@ -42,6 +47,9 @@ semantic versioning. Instead, releases are made in-line with those of the `typescript` compiler, which does not follow semantic versioning. We recommend you upgrade your `devDependency` on `jsii` to use a tilde range (e.g: `~4.7.0`) to be able to control when you migrate to future [TypeScript] language versions. +New `jsii` and `jsii-rosetta` features will only be introduced in the _latest_ +release line, while older release lines only receive bug fixes until they are +delcared end-of-life. ``` ### `README.md` for the `jsii` compiler @@ -201,6 +209,67 @@ back-ported to non-current release lines. Previous release lines will be considered *end-of-life* 12 months after they were superceded by a new *current* line. +Below is a chart of what this would have looked like if this proposal was +enacted ahead of TypeScript 4.0 being released, and new `jsii` release lines +were perfectly synchronized with TypeScript releases: + +```mermaid +gantt + title Support Policy Example + axisFormat %Y-%m + todayMarker off + + section 1.x + Current :crit, 2020-01-01,2020-08-20 + Active (6 months) :2020-08-20,2021-02-20 + Maintenance (1 year) :2021-02-20,2023-02-20 + End-of-Life :milestone, 0d + + section 4.0.x + Current :crit, 2020-08-20, 2020-11-19 + Maintenance (1 year) :2021-11-19 + End-of-Life :milestone, 0d + + section 4.1.x + Current :crit, 2020-11-19, 2021-02-23 + Maintenance (1 year) :2022-02-23 + End-of-Life :milestone, 0d + + section 4.2.x + Current :crit, 2021-02-23, 2021-05-26 + Maintenance (1 year) :2022-05-26 + End-of-Life :milestone, 0d + + section 4.3.x + Current :crit, 2021-05-26, 2021-08-26 + Maintenance (1 year) :2022-08-26 + End-of-Life :milestone, 0d + + section 4.4.x + Current :crit, 2021-08-26, 2021-11-17 + Maintenance (1 year) :2022-11-17 + End-of-Life :milestone, 0d + + section 4.5.x + Current :crit, 2021-11-17, 2022-02-28 + Maintenance (1 year) :2023-02-28 + End-of-Life :milestone, 0d + + section 4.6.x + Current :crit, 2022-02-28, 2022-05-24 + Maintenance (1 year) :2023-05-24 + End-of-Life :milestone, 0d + + section 4.7.x + Current :crit, 2022-05-24, 2022-08-25 + Maintenance (1 year) :2023-08-25 + End-of-Life :milestone, 0d + + section 4.8.x + Current :crit, 2022-08-25, 12w + %% 4.8 is the current TypeScript release at time of writing... +``` + ## Internal FAQ ### How will we maintain backwards compatibility? From 95f120e41847a7506e719d69529ff946c1935667 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Wed, 21 Sep 2022 11:40:46 +0200 Subject: [PATCH 14/24] refresh versions in the doc --- text/0374-jsii-ts-version.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 1377ff33a..2bbacc7e1 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -45,7 +45,7 @@ BREAKING CHANGE: In order to allow developers to use the latest & greatest features of TypeScript, the `jsii` compiler and `jsii-rosetta` no longer follow semantic versioning. Instead, releases are made in-line with those of the `typescript` compiler, which does not follow semantic versioning. We recommend -you upgrade your `devDependency` on `jsii` to use a tilde range (e.g: `~4.7.0`) +you upgrade your `devDependency` on `jsii` to use a tilde range (e.g: `~4.9.0`) to be able to control when you migrate to future [TypeScript] language versions. New `jsii` and `jsii-rosetta` features will only be introduced in the _latest_ release line, while older release lines only receive bug fixes until they are @@ -85,7 +85,7 @@ When setting up a `jsii` project, we recommend pinning the dependency on the // ... "devDependencies": { // ... - "jsii": "~4.7.0", + "jsii": "~4.9.0", // ... }, // ... @@ -126,7 +126,7 @@ When using `jsii-rosetta` in a project, we recommend pinning the dependency on // ... "devDependencies": { // ... - "jsii-rosetta": "~4.7.0", + "jsii-rosetta": "~4.9.0", // ... }, // ... @@ -198,7 +198,7 @@ bugs and security issues. The `v1` release line will remain in *Maintenace* for ### What is the support policy for these new releases? -Starting with release `4.7.0`, new features will only be added to the *current* +Starting with release `4.9.0`, new features will only be added to the *current* release line (the *latest* `major.minor` stream), which corresponds to the currently active [TypeScript] release line. @@ -341,7 +341,7 @@ change that customers may not expect. The proposed delivery plan for this feature is as follows: * Communicate about the upcoming change in new releases on the `v1` release - line, including a planned timeline for the initial release of the `v4.7` line, + line, including a planned timeline for the initial release of the `v4.9` line, and language about the departure from [SemVer]. * **Optional:** Separate the `jsii` compiler from the rest of packages in the @@ -368,9 +368,9 @@ The proposed delivery plan for this feature is as follows: - See proof-of-concept: [`aws/jsii#3501`][aws/jsii-3501] -* Release the initial `jsii` release on the `4.7` line (for practical reasons, +* Release the initial `jsii` release on the `4.9` line (for practical reasons, we will disregard [TypeScript] releases between `3.9` and the _current_ - version when this proposal is implemented, which at time of writing is `4.7`). + version when this proposal is implemented, which at time of writing is `4.8`). * Formally announce that the `v1` release line of `jsii` will move into the *Maintenance* tier of the [AWS SDKs and Tools maintenance policy][aws-policy] @@ -434,8 +434,8 @@ documentation for customers to understand what they are upgrading to. The release model used by `cdk8s-plus` involves releasing a different package for each version of the underlying resources (e.g: `cdk8s-plus-22` targets version 22 of the resources). A similar model could be used for `jsii`, where a -package named `jsii-4.7` could be released for the compiler that builds on -[TypeScript] `4.7.x`. +package named `jsii-4.9` could be released for the compiler that builds on +[TypeScript] `4.9.x`. This release pattern however creates an opportunity for supply-chain attacks as a malicious party could release `jsii-4.10` ahead of us and possibly exploit @@ -443,7 +443,7 @@ unsuspecting users. The attack vector can be mitigated by scoping the packages since npm scopes provide ownership guarantees, which would require releasing -`@jsii/typescript-4.7`. However this approach makes it more difficult for +`@jsii/typescript-4.9`. However this approach makes it more difficult for customers to know when a new release of the compiler is available, since dependency maintenance automation will only look for new versions of the same package. From 68632678d85db14f4f618a62d5402e9fe83ce836 Mon Sep 17 00:00:00 2001 From: Romain Marcadier Date: Mon, 26 Sep 2022 10:19:24 +0200 Subject: [PATCH 15/24] Update text/0374-jsii-ts-version.md Co-authored-by: Momo Kornher --- text/0374-jsii-ts-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 2bbacc7e1..30edcaceb 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -25,7 +25,7 @@ compiler does not conform to [semantic versioning][semver]). New features will only be introduced on the `jsii` release line that targets the latest [TypeScript] compiler. -Users may need to modify they code when upgrading from one `major.minor` release +Users may need to modify their code when upgrading from one `major.minor` release line to another (addressing [TypeScript] language evolutions and `jsii` feature evolutions). While upgrading to the latest release line of `jsii` helps minimize the effort required for these updates, the release strategy allows developers to From a9151f59548cc210f75fa220de423b129e79bb8c Mon Sep 17 00:00:00 2001 From: Romain Marcadier Date: Mon, 26 Sep 2022 10:19:34 +0200 Subject: [PATCH 16/24] Update text/0374-jsii-ts-version.md Co-authored-by: Momo Kornher --- text/0374-jsii-ts-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 30edcaceb..a000a6804 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -17,7 +17,7 @@ libraries, so as to remain completely backwards compatible. ### Release Notes entry -```md +```markdown Starting with this release, the `jsii` compiler and `jsii-rosetta` will no longer conform to [semantic versioning][semver]. Instead, its `major.minor` version will match that of the [TypeScript] compiler it uses (the [TypeScript] From 6048f721033781ae58009aa50cae40038543a912 Mon Sep 17 00:00:00 2001 From: Romain Marcadier Date: Tue, 25 Oct 2022 10:09:31 +0200 Subject: [PATCH 17/24] Update text/0374-jsii-ts-version.md Co-authored-by: Ansgar Mertens --- text/0374-jsii-ts-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index a000a6804..fff7d60d8 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -290,7 +290,7 @@ of `jsii`. This can be achieved using the [`downlevel-dts`][downlevel-dts] utility. Failure to do so may make it impossible to use a library compiled with a given release of `jsii` in a project that is still using an older release, which would be akin to forcing dependents to upgrade at the same pace as their -dependencies (which is undersiable). +dependencies (which is undesirable). ### Why are we doing this? From fdef4d2d4e1dab83279c0d97a4747565b68c7d90 Mon Sep 17 00:00:00 2001 From: Romain Marcadier Date: Tue, 25 Oct 2022 10:09:42 +0200 Subject: [PATCH 18/24] Update text/0374-jsii-ts-version.md Co-authored-by: Ansgar Mertens --- text/0374-jsii-ts-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index fff7d60d8..3e4698b48 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -414,7 +414,7 @@ to re-export a `namespace` including all the type declarations it contains, as entities with a run-time value, and none of the interfaces it contains. The consequence of this is that writing an adapter for a particular [TypeScript] version requires wrapping all useful functions of the compiler API and -re-delcaring the types they use, which represents hundreds if not thousands of +re-declaring the types they use, which represents hundreds if not thousands of lines of code for each supported version. #### Only de-couple the `jsii` package version, but stick with [SemVer] From 51bcd075dc275c098d58f41bb6ef25cc3d7fd1ce Mon Sep 17 00:00:00 2001 From: Romain Marcadier Date: Tue, 25 Oct 2022 10:09:51 +0200 Subject: [PATCH 19/24] Update text/0374-jsii-ts-version.md Co-authored-by: Ansgar Mertens --- text/0374-jsii-ts-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 3e4698b48..32facaab7 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -400,7 +400,7 @@ are caught by surprise, or have broken expectations. #### Bring-your-own TypeScript version One of the main rationales for this change is to enable the use of new -TypeScript releases without forcing the enitre package ecosystem to make the +TypeScript releases without forcing the entire package ecosystem to make the change at the same time (due to language-breaking changes). An option to address this would be to allow customers to "bring their own" From e2fe12debbacc63a42b520297ffdfa0dbc4ae4e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Tue, 25 Oct 2022 10:24:55 +0200 Subject: [PATCH 20/24] chore: alternate scenarios for maintenance windows --- text/0374-jsii-ts-version.md | 136 ++++++++++++++++++++++++++++++++++- 1 file changed, 134 insertions(+), 2 deletions(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 32facaab7..b9c95a9aa 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -215,14 +215,14 @@ were perfectly synchronized with TypeScript releases: ```mermaid gantt - title Support Policy Example + title Support Policy Example (assuming 1 year maintenance) axisFormat %Y-%m todayMarker off section 1.x Current :crit, 2020-01-01,2020-08-20 Active (6 months) :2020-08-20,2021-02-20 - Maintenance (1 year) :2021-02-20,2023-02-20 + Maintenance (1 year) :2021-02-20,2022-02-20 End-of-Life :milestone, 0d section 4.0.x @@ -270,6 +270,138 @@ gantt %% 4.8 is the current TypeScript release at time of writing... ``` +
+Alternate Scenario (6 months maintenance) + +Shortening the maintenance window to 6 months instead of 12 allows reducing the +amount of previous lines that are maintained at any given time to 2 to 3, at the +expense of increased pressure on customers to migrate to newer versions. + +```mermaid +gantt + title Support Policy Example (assuming 6 months maintenance) + axisFormat %Y-%m + todayMarker off + + section 1.x + Current :crit, 2020-01-01,2020-08-20 + Active (6 months) :2020-08-20,2021-02-20 + Maintenance (6 months) :2021-02-20,2021-08-20 + End-of-Life :milestone, 0d + + section 4.0.x + Current :crit, 2020-08-20, 2020-11-19 + Maintenance (6 months) :2021-05-19 + End-of-Life :milestone, 0d + + section 4.1.x + Current :crit, 2020-11-19, 2021-02-23 + Maintenance (6 months) :2021-08-23 + End-of-Life :milestone, 0d + + section 4.2.x + Current :crit, 2021-02-23, 2021-05-26 + Maintenance (6 months) :2021-11-26 + End-of-Life :milestone, 0d + + section 4.3.x + Current :crit, 2021-05-26, 2021-08-26 + Maintenance (6 months) :2022-02-26 + End-of-Life :milestone, 0d + + section 4.4.x + Current :crit, 2021-08-26, 2021-11-17 + Maintenance (6 months) :2022-05-17 + End-of-Life :milestone, 0d + + section 4.5.x + Current :crit, 2021-11-17, 2022-02-28 + Maintenance (6 months) :2022-08-28 + End-of-Life :milestone, 0d + + section 4.6.x + Current :crit, 2022-02-28, 2022-05-24 + Maintenance (6 months) :2022-11-24 + End-of-Life :milestone, 0d + + section 4.7.x + Current :crit, 2022-05-24, 2022-08-25 + Maintenance (6 months) :2023-02-25 + End-of-Life :milestone, 0d + + section 4.8.x + Current :crit, 2022-08-25, 12w + %% 4.8 is the current TypeScript release at time of writing... +``` +
+ +
+Alternate Scenario (current + previous) + +Adopting a maintenace policy similar to that of the Go compiler toolchain +guarantees only one previous release line needs maintenance at any given time, +as this is the gist of the maintenance policy: + +> We support the past two *TypeScript* releases. For example, 4.7 a,d 4.8 when +> 4.8 is the latest active release. + +```mermaid +gantt + title Support Policy Example (current + previous) + axisFormat %Y-%m + todayMarker off + + section 1.x + Current :crit, 2020-01-01,2020-08-20 + Active (6 months) :2020-08-20,2021-02-20 + Maintenance (1 year) :2021-02-20,2022-02-20 + End-of-Life :milestone, 0d + + section 4.0.x + Current :crit, 2020-08-20, 2020-11-19 + Maintenance :2021-02-23 + End-of-Life :milestone, 0d + + section 4.1.x + Current :crit, 2020-11-19, 2021-02-23 + Maintenance :2021-05-26 + End-of-Life :milestone, 0d + + section 4.2.x + Current :crit, 2021-02-23, 2021-05-26 + Maintenance :2021-08-26 + End-of-Life :milestone, 0d + + section 4.3.x + Current :crit, 2021-05-26, 2021-08-26 + Maintenance :2021-11-17 + End-of-Life :milestone, 0d + + section 4.4.x + Current :crit, 2021-08-26, 2021-11-17 + Maintenance :2022-02-28 + End-of-Life :milestone, 0d + + section 4.5.x + Current :crit, 2021-11-17, 2022-02-28 + Maintenance :2022-05-24 + End-of-Life :milestone, 0d + + section 4.6.x + Current :crit, 2022-02-28, 2022-05-24 + Maintenance :2022-08-25 + End-of-Life :milestone, 0d + + section 4.7.x + Current :crit, 2022-05-24, 2022-08-25 + Maintenance :2022-08-25, 12w + + section 4.8.x + Current :crit, 2022-08-25, 12w + %% 4.8 is the current TypeScript release at time of writing... +``` +
+ ## Internal FAQ ### How will we maintain backwards compatibility? From 21ee11da8afd80239a0e60c621ac4edae383cf11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Tue, 25 Oct 2022 10:39:54 +0200 Subject: [PATCH 21/24] chore: re-phrase to focus less on SemVer and more on the two version lines --- text/0374-jsii-ts-version.md | 52 +++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index b9c95a9aa..19d53ad77 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -18,12 +18,25 @@ libraries, so as to remain completely backwards compatible. ### Release Notes entry ```markdown -Starting with this release, the `jsii` compiler and `jsii-rosetta` will no -longer conform to [semantic versioning][semver]. Instead, its `major.minor` -version will match that of the [TypeScript] compiler it uses (the [TypeScript] -compiler does not conform to [semantic versioning][semver]). New features will -only be introduced on the `jsii` release line that targets the latest -[TypeScript] compiler. +Starting with this release, all packages in the *jsii* toolchain that internally +use the [TypeScript] compiler (i.e: `jsii` and `jsii-rosetta`) will be released +on a new release line that uses the same `major.minor` number as the +[TypeScript] compiler they are built against. All other packages (such as +`@jsii/spec`, `jsii-pacmak`, etc...) will continue to be released against the +same `1.x` release line they are currently released in. + +The [TypeScript] compiler does not conform to [semantic versioning][semver]), +and instead guarantees the absence of breaking changes within a given +`major.minor` release line. We recommend developers model their dependencies on +`jsii` and `jsii-rosetta` using a minor-pinned version range (e.g: `~4.9.0`) in +order to avoid new [TypeScript] language versions breaking their codebases at +undesirable times. + +New features will be introduced only in the *latest* `major.minor` release line +of `jsii` and `jsii-rosetta` (typically corresponding to the current stable +release of the [TypeScript] compiler). Breaking changes may be introduced with +every new `major.minor` release line and will continue to be documented in the +CHANGELOG. Users may need to modify their code when upgrading from one `major.minor` release line to another (addressing [TypeScript] language evolutions and `jsii` feature @@ -35,21 +48,16 @@ This change is made to allow developers to benefit from the latest and greatest features of the [TypeScript] language without requiring the entire ecosystem to make the switch at the same time. -Other packages in the jsii toolchain (such as `jsii-pacmak`, `@jsii/spec`, and -others) are not affected by this change and will continue to follow [semantic -versioning][semver] as they currently do. The bindings generated by -`jsii-pacmak` will also remain backwards compatible, as code generation is not -impacted by this change in any way. - BREAKING CHANGE: In order to allow developers to use the latest & greatest -features of TypeScript, the `jsii` compiler and `jsii-rosetta` no longer follow -semantic versioning. Instead, releases are made in-line with those of the -`typescript` compiler, which does not follow semantic versioning. We recommend -you upgrade your `devDependency` on `jsii` to use a tilde range (e.g: `~4.9.0`) -to be able to control when you migrate to future [TypeScript] language versions. -New `jsii` and `jsii-rosetta` features will only be introduced in the _latest_ -release line, while older release lines only receive bug fixes until they are -delcared end-of-life. +features of TypeScript, the `jsii` compiler and `jsii-rosetta` are now made +in-line with those of the `typescript` compiler (e.g: `jsii@4.9.x` is built on +TypeScript 4.9.x). Since the TypeScript compiler does not follow semantic +versioning, we strongly recommend you upgrade your `devDependency` on `jsii` and +`jsii-rosetta` to use a tilde range (e.g: `~4.9.0`) to be able to control when +you migrate to future [TypeScript] language versions. New `jsii` and +`jsii-rosetta` features will only be introduced in the _latest_ release line, +while older release lines only receive bug fixes until they are delcared +end-of-life. ``` ### `README.md` for the `jsii` compiler @@ -98,8 +106,8 @@ When setting up a `jsii` project, we recommend pinning the dependency on the ````md In order to allow developers to access and leverage the latest and greatest of *TypeScript* language features, `jsii-rosetta` releases follow the `typescript` -package releases. For example, `jsii-rosetta` version `4.3.x` is built on top of -version `4.3.x` of the `typescript` compiler. +package releases. For example, `jsii-rosetta` version `4.9.x` is built on top of +version `4.9.x` of the `typescript` compiler. Going forward, new `jsii-rosetta` features will only be introduced in the _latest_ available release line (corresponding to the latest TypeScript From a53cea4fd28a14dbee0d2b90dae752156aaae045 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=A7=91=F0=9F=8F=BB=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier?= Date: Tue, 25 Oct 2022 10:49:23 +0200 Subject: [PATCH 22/24] add words about significant compiler features w/ language impact --- text/0374-jsii-ts-version.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 19d53ad77..ffa7b884b 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -476,6 +476,18 @@ be difficult due to the amount of breaking changes in the [TypeScript] compiler API between releases). Diverging from this [policy][aws-policy] is a significant change that customers may not expect. +Additionally, since we cannot afford to back-port new features (especially if +significant) on older releases, this means users may need to update their code +in order to gain access to new features introduced in the compiler. While this +may be a desirable forcing function on developers to upgrade to the latest +release line, it may impose challenges when such features cannot be implemented +in a way that is compatible with previous versions of the compiler (e.g: it may +be difficult or impossible to implement [RFC 193][RFC193] in a backwards +compatible manner, as it likely requires the introduction of a new type kind, +which previous release lines would not recognize). + +[RFC193]: https://github.com/aws/aws-cdk-rfcs/pull/194 + ### What is the technical solution (design) of this feature? The proposed delivery plan for this feature is as follows: From 0bde9329ff3eab549a9f5a9b58ba871d07dfaec0 Mon Sep 17 00:00:00 2001 From: Romain Marcadier Date: Mon, 7 Nov 2022 10:21:02 +0100 Subject: [PATCH 23/24] Update text/0374-jsii-ts-version.md Co-authored-by: Calvin Combs <66279577+comcalvi@users.noreply.github.com> --- text/0374-jsii-ts-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index ffa7b884b..9ec0dafd7 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -56,7 +56,7 @@ versioning, we strongly recommend you upgrade your `devDependency` on `jsii` and `jsii-rosetta` to use a tilde range (e.g: `~4.9.0`) to be able to control when you migrate to future [TypeScript] language versions. New `jsii` and `jsii-rosetta` features will only be introduced in the _latest_ release line, -while older release lines only receive bug fixes until they are delcared +while older release lines only receive bug fixes until they are declared end-of-life. ``` From 88fd49e67226fd95dda8fb62421ac1cf20a90ae3 Mon Sep 17 00:00:00 2001 From: Momo Kornher Date: Fri, 13 Oct 2023 18:41:00 +0100 Subject: [PATCH 24/24] fix style --- text/0374-jsii-ts-version.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0374-jsii-ts-version.md b/text/0374-jsii-ts-version.md index 9ec0dafd7..854a32d87 100644 --- a/text/0374-jsii-ts-version.md +++ b/text/0374-jsii-ts-version.md @@ -341,6 +341,7 @@ gantt Current :crit, 2022-08-25, 12w %% 4.8 is the current TypeScript release at time of writing... ``` +
@@ -408,6 +409,7 @@ gantt Current :crit, 2022-08-25, 12w %% 4.8 is the current TypeScript release at time of writing... ``` +
## Internal FAQ