chore(release): 1.81.0 (#4087)

See [CHANGELOG](https://github.com/aws/jsii/blob/bump/1.81.0/CHANGELOG.md)

Author: mergify[bot]

.github/workflows/yarn-upgrade.yml

@@ -130,7 +130,7 @@ jobs:
         run: '[ -s ${{ runner.temp }}/upgrade.patch ] && git apply ${{ runner.temp }}/upgrade.patch || echo "Empty patch. Skipping."'
 
       - name: Make Pull Request
-        uses: peter-evans/create-pull-request@v4
+        uses: peter-evans/create-pull-request@v5
         with:
           # Git commit details
           author: 'AWS CDK Automation <aws-cdk-automation@users.noreply.github.com>'

.mergify/config.yml

@@ -30,7 +30,7 @@ pull_request_rules:
       label:
         add: [contribution/core]
     conditions:
-      - author~=^(RomainMuller|rix0rrr|Jerry-AWS|MrArnoldPalmer|iliapolo|madeline-k|comcalvi|kaizencc|corymhall|otaviomacedo|yuth|TheRealAmazonKendra|vinayak-kukreja|mrgrain|ryparker|Naumel)$
+      - author~=^(RomainMuller|rix0rrr|Jerry-AWS|MrArnoldPalmer|iliapolo|madeline-k|comcalvi|kaizencc|corymhall|otaviomacedo|yuth|TheRealAmazonKendra|vinayak-kukreja|mrgrain|ryparker|Naumel|colifran)$
       - -label~="contribution/core"
   - name: Tell them we're good now
     actions:

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.81.0](https://github.com/aws/jsii/compare/v1.80.0...v1.81.0) (2023-05-10)
+
+
+### Features
+
+* **jsii-diff:** allow external stability to be treated as error ([#4076](https://github.com/aws/jsii/issues/4076)) ([95689ea](https://github.com/aws/jsii/commit/95689ea840a99f38f8449aab2bc452cf489e3e3f))
+* **jsii-pacmak:** parsing arguments in non-strict mode ([#4068](https://github.com/aws/jsii/issues/4068)) ([3d49d6f](https://github.com/aws/jsii/commit/3d49d6fd2dc64db45aa3f1164bb976c8cfe75175)), closes [#3465](https://github.com/aws/jsii/issues/3465)
+
+
+### Bug Fixes
+
+* **pacmak:** go docs overview displays repeating description ([#4081](https://github.com/aws/jsii/issues/4081)) ([4fd596a](https://github.com/aws/jsii/commit/4fd596a467cdb422ebea3fdf01d068bc360b3757)), closes [/github.com/aws/jsii/pull/3698/files#diff-0a99c713a1282d6efe349c932d74dbfbdf1d926834c46ebfb5d65daeb27073f3R263](https://github.com/aws//github.com/aws/jsii/pull/3698/files/issues/diff-0a99c713a1282d6efe349c932d74dbfbdf1d926834c46ebfb5d65daeb27073f3R263) [/github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/package.json#L4](https://github.com/aws//github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/package.json/issues/L4) [/github.com/aws/jsii/blob/main/packages/jsii-reflect/lib/assembly.ts#L46-L52](https://github.com/aws//github.com/aws/jsii/blob/main/packages/jsii-reflect/lib/assembly.ts/issues/L46-L52)
+* **rosetta:** flakey trim-cache test ([#4043](https://github.com/aws/jsii/issues/4043)) ([f70c0f7](https://github.com/aws/jsii/commit/f70c0f77069c8beb30010395cfd5817ac013feba))
+
 ## [1.80.0](https://github.com/aws/jsii/compare/v1.79.0...v1.80.0) (2023-04-04)
 
 

README.md

@@ -20,6 +20,19 @@ usual), but also in **Python**, **Java**, **C#** (and other languages from the _
 
 Head over to our [documentation website](https://aws.github.io/jsii)!
 
+The jsii toolchain is spread out on multiple repositories:
+- [aws/jsii-compiler](https://github.com/aws/jsii-compiler) is where the `jsii` compiler is maintained (except releases
+  in the `1.x` line, which are maintained in this repository)
+- [aws/jsii-rosetta](https://github.com/aws/jsii-rosetta) is where the `jsii-rosetta` sample code transliteration tool
+  is maintained (except releases in the `1.x` line, which are maintained in this repository)
+- [aws/jsii](https://github.com/aws/jsii) is where the rest of the toolchain is maintained, including:
+  - `@jsii/spec`, the package that defines the *`.jsii` assembly* specification
+  - `jsii-config`, an interactive tool to help configure your jsii package
+  - `jsii-pacmak`, the bindings generator for jsii packages
+  - `jsii-reflect`, a higher-level way to process *`.jsii` assemblies*
+  - The jsii runtime libraries for the supported jsii target languages
+  - `1.x` release lines of `jsii` and `jsii-rosetta`
+
 # :book: Blog Posts
 
 Here's a collection of blog posts (in chronological order) related to `jsii`:

gh-pages/content/compiler-and-rosetta-maintenance.md

@@ -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.
+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.

gh-pages/content/overview/toolchain.md

@@ -5,34 +5,43 @@
 !!! info
     We are considering creating an "umbrella entrypoint" to make it easier to consume.
 
-| Name           | Stability    | Description                                                           |
-| -------------- | ------------ | --------------------------------------------------------------------- |
-| [jsii]         | Stable       | Compiles TypeScript to jsii module                                    |
-| [jsii-pacmak]  | Stable       | Creates ready-to-publish language-specific packages from jsii modules |
-| [jsii-reflect] | Stable       | Strong-typed reflection library for jsii type systems                 |
-| [jsii-diff]    | Stable       | API backwards compatibility checker                                   |
-| [jsii-rosetta] | Experimental | Transpile code snippets (in docs) from TypeScript to jsii languages   |
-| [jsii-config]  | Experimental | Interactive tool for generating jsii configuration                    |
-| [jsii-release] | Community    | Publishes jsii modules to all supported package managers              |
-| [jsii-srcmak]  | Community    | Generates relocatable source code in jsii languages from typescript   |
-| [jsii-docgen]  | Community    | Generates markdown API documentation for jsii modules                 |
+| 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"
-    - **Stable**: Projects that comply with the [Semantic Versioning][semver] specification, and will hence not change
-      behavior or receive other breaking changes across minor and patch version bumps.
+    - **GA**: Projects that are deemed *Generally Available* and for which customers can expect full support, including
+      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
 
 
-[jsii]: https://github.com/aws/jsii/tree/main/packages/jsii
+[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-rosetta]: https://github.com/aws/jsii/tree/main/packages/jsii-rosetta
+[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

gh-pages/mkdocs.yml

@@ -18,6 +18,8 @@ nav:
           - overview/features.md
           - overview/toolchain.md
           - overview/runtime-architecture.md
+      - Maintenance Announcements:
+          - jsii@v1.x & jsii-rosetta@v1.x: compiler-and-rosetta-maintenance.md
   - ...
 
 extra:

gh-pages/requirements-dev.txt

@@ -1,4 +1,4 @@
 mkdocs~=1.4.2
-mkdocs-awesome-pages-plugin~=2.8.0
-mkdocs-material~=9.1.5
+mkdocs-awesome-pages-plugin~=2.9.0
+mkdocs-material~=9.1.8
 mkdocs-git-revision-date-plugin~=0.3.2

lerna.json

@@ -10,5 +10,5 @@
       "rejectCycles": true
     }
   },
-  "version": "1.80.0"
+  "version": "1.81.0"
 }

package.json

@@ -16,15 +16,15 @@
   },
   "devDependencies": {
     "@jest/types": "^28.1.3",
-    "@types/jest": "^29.5.0",
+    "@types/jest": "^29.5.1",
     "@types/node": "^14.18.42",
-    "@typescript-eslint/eslint-plugin": "^5.57.0",
-    "@typescript-eslint/parser": "^5.57.0",
+    "@typescript-eslint/eslint-plugin": "^5.59.0",
+    "@typescript-eslint/parser": "^5.59.0",
     "all-contributors-cli": "^6.24.0",
-    "eslint": "^8.37.0",
+    "eslint": "^8.38.0",
     "eslint-config-prettier": "^8.8.0",
     "eslint-import-resolver-node": "^0.3.7",
-    "eslint-import-resolver-typescript": "^3.5.3",
+    "eslint-import-resolver-typescript": "^3.5.5",
     "eslint-plugin-import": "2.26.0",
     "eslint-plugin-prettier": "^4.2.1",
     "jest": "^29.5.0",