docs: publish jsii@1.x and jsii-rosetta@1.x maintenance announcement #4067
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,142 @@ | ||||||
| # Maintenance Announcement: `jsii` & `jsii-rosetta` 1.x | ||||||
|
|
||||||
| **Announcement Date:** `2023-04-24` | ||||||
|
|
||||||
| We have recently released `jsii@5.0.0` and `jsii-rosetta@5.0.0`, built on the TypeScript `5.0.x` compiler, allowing | ||||||
| package maintainers to migrate to a more modern TypeScript language version than 3.9 (which the `1.x` release line is | ||||||
| built on). This change was designed in [RFC-374], and removes the need for developers to pin some of their dependencies | ||||||
| to releases still compatible with TypeScript 3.9 without necessarily requiring their dependents to do the same at the | ||||||
| same time. Upgrading your `jsii` and `jsii-rosetta` dependencies to `v5.0.x` is transparent to your users. | ||||||
|
|
||||||
| [RFC-374]: https://github.com/aws/aws-cdk-rfcs/blob/rmuller/jsii-version-unlock/text/0374-jsii-ts-version.md | ||||||
|
|
||||||
| Starting with the `5.0.x` release of `jsii` and `jsii-rosetta`, we are using a new versioning strategy for these two | ||||||
| tools. Going forward we will closely follow new TypeScript compiler releases with new `jsii` and `jsii-rosetta` releases, | ||||||
| enabling the entire jsii developer community to adopt new TypeScript syntax & benefit from bug fixes and | ||||||
| performance enhancements brought into the TypeScript compiler, while retaining the ability control the timeline of these | ||||||
| upgrades. | ||||||
|
|
||||||
| We believe the new versioning strategy will result in an improved developer experience for jsii library maintainers, and | ||||||
| have decided to start the process of retiring the `1.x` release line. In accordance with our maintenance commitment for | ||||||
| the `1.x` release line, the retirement timeline is the following: | ||||||
|
|
||||||
| * On `2023-04-24`, `jsii@1.x` and `jsii-rosetta@1.x` will enter the **Maintenance Announcement** stage. During this | ||||||
| stage, they will continue to be actively maintained, including new features back-ported from the current release | ||||||
| (`5.0.x` or later), bug fixes, and security updates. | ||||||
| * On `2023-10-31` (six months later), the releases will move into the **Maintenance** stage. During this stage, they | ||||||
| will continue receiving bug fixes and security updates, but will no longer receive new features. | ||||||
| * On `2024-10-31` (one year later), the releases will finally reach **End-of-Support**, and will no longer receive any | ||||||
| features, bug fixes, or security udpates. | ||||||
|
|
||||||
| Future `1.x` releases of `jsii` and `jsii-rosetta` will soon start displaying a warning when used, encouraging customers | ||||||
| to migrate to the newer releases, which we believe will provide a better experience. | ||||||
|
|
||||||
| ## Frequently Asked Questions | ||||||
|
|
||||||
| ### How difficult is it to migrate from `1.x` to `5.0.x`? | ||||||
|
|
||||||
| The TypeScript language incurred a number of breaking changes between 3.9 and 5.0, including the following: | ||||||
|
|
||||||
| * Catch bindings are typed as `unknown` by default instead of being implicitly `any` | ||||||
| * You may need to explicitly type catch bindings as any: `catch (e)` → `catch (e: any)` | ||||||
| * It is no longer allowed to declare abstract methods `async` | ||||||
| * Simply remove the `async` keyword from `abstract` method declarations | ||||||
| * Additional breaking changes may affect your code, and you can read more about these on the TypeScript release notes | ||||||
| for the respective versions: | ||||||
| * [TypeScript 4.0 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-0/) | ||||||
| * [TypeScript 4.1 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-1/) | ||||||
| * [TypeScript 4.2 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-2/) | ||||||
| * [TypeScript 4.3 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-3/) | ||||||
| * [TypeScript 4.4 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-4/) | ||||||
| * [TypeScript 4.5 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-5/) | ||||||
| * [TypeScript 4.6 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-6/) | ||||||
| * [TypeScript 4.7 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-7/) | ||||||
| * [TypeScript 4.8 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-8/) | ||||||
| * [TypeScript 4.9 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-9/) | ||||||
| * [TypeScript 5.0 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/) | ||||||
|
|
||||||
| In addition to these, two import changes affect jsii exported APIs specifically: | ||||||
|
|
||||||
| * The `1.x` release line silently ignores index signatures (these are hence unavailable in other languages), and the | ||||||
| `5.0.x` release starts explicitly rejecting these | ||||||
| * You can explicitly opt into the `1.x` behavior by adding the `@jsii ignore` doc-tag: | ||||||
| ```ts hl_lines="5" | ||||||
| export interface Example { | ||||||
| /** | ||||||
| * This API is not visible in non-TS/JS languages. | ||||||
| * | ||||||
| * @jsii ignore | ||||||
| */ | ||||||
| readonly [key: string]: any; | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| * The `1.x` release line incorrectly interprets tuple types as synonyms to `object` (resulting in those APIs often being | ||||||
| unusable from other languages), and the `5.0.x` release starts explicitly rejecting these | ||||||
| * These APIs need to be replaced. You can use the `@jsii ignore` doc-tag to explicitly opt these APIs out of the | ||||||
| multi-language supported API, and provide an alternate API: | ||||||
| ```ts hl_lines="3-4 8" | ||||||
| export class Example { | ||||||
| /** | ||||||
| * @jsii ignore | ||||||
| * @deprecated Prefer using `newMethod` instead. | ||||||
| */ | ||||||
| public method(): [string, number] { /* ... */ } | ||||||
|
|
||||||
| public newMethod(): StringAndNumber { /* ... */ } | ||||||
| } | ||||||
|
|
||||||
| export interface StringAndNumber { | ||||||
| readonly stringValue: string; | ||||||
| readonly numberValue: number; | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ### What happens with other packages of the jsii toolchain (`jsii-pacmak`, `jsii-config`, etc...)? | ||||||
|
|
||||||
| The new versioning strategy only affects the `jsii` and `jsii-rosetta` packages. All other parts of the jsii toolchain | ||||||
| will continue to be released under the `1.x` release line for the foreseeable future. The compilation artifacts produced | ||||||
| by `jsii@5.0.0` and newer remain compatible with jsii tools from the `1.x` toolchain, so developers do not have to coordinate | ||||||
| upgrades with their dependents and dependencies. | ||||||
|
|
||||||
| ### If I upgrade my package to `jsii@5.0.0`, are my dependents required to do the same? | ||||||
|
|
||||||
| You can decide to upgrade your `jsii` compiler as well as `jsii-rosetta` independently from your dependencies and | ||||||
| dependents. Output artifacts are compatible across all tool releases, including the `1.x` line, at least until they | ||||||
| reach *End-of-Support*. | ||||||
|
|
||||||
| ### Can my app have dependencies built by different `jsii` release lines? | ||||||
|
|
||||||
| The `jsii` compiler and `jsii-rosetta` versions used to build a library has no material impact on the runtime artifacts. | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. I think this changes the meaning of the sentence (which is there to say your choice of compilers doesn't affect your consumers). |
||||||
| The underlying runtime platform remains unchanged, and developers do not need to worry about which version of the | ||||||
| compiler was used to produce their dependencies. | ||||||
|
|
||||||
| ### How often will new `jsii` & `jsii-rosetta` release lines be started? | ||||||
|
|
||||||
| New releases will closely follow those of the TypeScript compiler, which are created approximately once per quarter. | ||||||
| While we encourage customers to migrate to the latest release line as quickly as possible, the updated _Support & | ||||||
| Maintenance Policy_ for these tools guarantees a minimum of six calendar months of bug fixes and security updates for | ||||||
| non-current release lines, so that users can migrate on their own schedule. | ||||||
|
|
||||||
| ### What is the support policy for the new `5.0.x` and newer releases? | ||||||
|
|
||||||
| The applicable maintenance and support policy is documented in the `SUPPORT.md` file of the | ||||||
| [`aws/jsii-compiler`][compiler-support] and [`aws/jsii-rosetta`][rosetta-support] repositories. The main aspects of the | ||||||
| new support policy are: | ||||||
|
|
||||||
| * Only the latest release line is deemed **Current**, and receives new features, bug fixes, and security updates; | ||||||
| * Once a release stops being **Current**, it moves into **Maintenance**, where it continues receiving bug fixes and | ||||||
| security updates, but no new features will be added; | ||||||
| * After six (6) months in **Maintenance**, a release line moves to **End-of-Support**, and is no longer maintained. | ||||||
|
|
||||||
| [compiler-support]: https://github.com/aws/jsii-compiler/blob/v5.0.0/SUPPORT.md | ||||||
| [rosetta-support]: https://github.com/aws/jsii-rosetta/blob/v5.0.0/SUPPORT.md | ||||||
|
|
||||||
| ### What happens if I continue using releases after they reach End-of-Support? | ||||||
|
|
||||||
| Once End-of-Support is declared for the releases, we will no longer be able to provide support, bug fixes, or security | ||||||
| updates for these releases. You may elect to continue to use them at your discretion (published releases will remain | ||||||
| available to download from the [npmjs.com](http://npmjs.com/) package registry indefinitely). You should be aware that, | ||||||
| although there is no plan to introduce non-backwards compatible features at this stage, it is possible that some of your | ||||||
| library’s dependencies may stop being compatible with `1.x` releases of the compiler in the future, and your library’s | ||||||
| dependents may at some point no longer be able to consume `1.x` compiler output artifacts. | ||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
|
|
@@ -5,34 +5,43 @@ | |||||||
| !!! info | ||||||||
| We are considering creating an "umbrella entrypoint" to make it easier to consume. | ||||||||
|
|
||||||||
| | Name | Release | Stability | Description | | ||||||||
| | --------------- | ------- | -------------- | --------------------------------------------------------------------- | | ||||||||
| | [jsii1] | `1.x` | [Maintenance] | Compiles TypeScript to jsii module (TypeScript 3.9 Syntax) | | ||||||||
| | [jsii] | `5.0.x` | GA | Compiles TypeScript to jsii module (TypeScript 5.0 Syntax) | | ||||||||
| | [jsii-pacmak] | `1.x` | GA | Creates ready-to-publish language-specific packages from jsii modules | | ||||||||
| | [jsii-reflect] | `1.x` | GA | Strong-typed reflection library for jsii type systems | | ||||||||
| | [jsii-diff] | `1.x` | GA | API backwards compatibility checker | | ||||||||
| | [jsii-rosetta1] | `1.x` | [Maintenance] | Transpile code snippets (in docs) from TypeScript to jsii languages | | ||||||||
| | [jsii-rosetta] | `5.0.x` | Experimental | Transpile code snippets (in docs) from TypeScript to jsii languages | | ||||||||
| | [jsii-config] | `1.x` | Experimental | Interactive tool for generating jsii configuration | | ||||||||
| | [jsii-release] | `1.x` | Community | Publishes jsii modules to all supported package managers | | ||||||||
| | [jsii-srcmak] | `1.x` | Community | Generates relocatable source code in jsii languages from typescript | | ||||||||
| | [jsii-docgen] | `1.x` | Community | Generates markdown API documentation for jsii modules | | ||||||||
|
|
||||||||
| ??? question "Stability Definitions" | ||||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. The See: https://python-markdown.github.io/extensions/admonition/ |
||||||||
| - **GA**: Projects that are deemed *Generally Available* and for which customers can expect full support, including | ||||||||
|
There was a problem hiding this comment.
Suggested change
The format looks strange when in preview (not a list). I am guessing it's a missing new line here. There was a problem hiding this comment. Yea... this is the specific markdown flavor that mkdoc uses... It's mostly compatible with GFM, but there's some minute differences... I did run a preview with |
||||||||
| new features, bug fixes, and security updates. | ||||||||
| - **Experimental**: Projects that are under active development and may change behavior or receive other breaking | ||||||||
| changes across minor releases. | ||||||||
| - **Community**: a community-maintained project, not officially supported by the *jsii core team*. | ||||||||
| - **[Maintenance]**: Project releases under *Maintenance* continue to receive full support, including new features, | ||||||||
| bug fixes, and security updates for a limited time before moving to *Support*. | ||||||||
| - **Support**: Deprecated projects no longer receive new features, and are only updated with severe bug fixes and | ||||||||
| security updates; until they are declared End-of-Support. | ||||||||
|
|
||||||||
| [semver]: https://semver.org/spec/v2.0.0.html | ||||||||
|
|
||||||||
|
|
||||||||
| [Maintenance]: ../compiler-and-rosetta-maintenance.md | ||||||||
| [jsii1]: https://github.com/aws/jsii/tree/main/packages/jsii | ||||||||
| [jsii]: https://github.com/aws/jsii-compiler#readme | ||||||||
| [jsii-pacmak]: https://github.com/aws/jsii/tree/main/packages/jsii-pacmak | ||||||||
| [jsii-reflect]: https://github.com/aws/jsii/tree/main/packages/jsii-reflect | ||||||||
| [jsii-config]: https://github.com/aws/jsii/tree/main/packages/jsii-config | ||||||||
| [jsii-diff]: https://github.com/aws/jsii/tree/main/packages/jsii-diff | ||||||||
| [jsii-rosetta1]: https://github.com/aws/jsii/tree/main/packages/jsii-rosetta | ||||||||
| [jsii-rosetta]: https://github.com/aws/jsii-rosetta#readme | ||||||||
| [jsii-release]: https://github.com/eladb/jsii-release | ||||||||
| [jsii-srcmak]: https://github.com/eladb/jsii-srcmak | ||||||||
| [jsii-docgen]: https://github.com/eladb/jsii-docgen | ||||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.