fix(pacmak): support jsii-rosetta 5.5 (#4619)

mrgrain · web-flow · commit 9ecea560bef8 · 2024-08-26T19:53:00.000Z
Declare support in peerDependencies and add integration test. Updated some docs while I'm at it. --- By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license]. [Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -438,6 +438,7 @@ jobs:
           - 5.2.x
           - 5.3.x
           - 5.4.x
+          - 5.5.x
     steps:
       # Check out the code
       - name: Download Artifact
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,12 +1,15 @@
 # Contributing to jsii
+
 Thanks for your interest in contributing to AWS JSII! :heart:
 
 This document describes how to set up a development environment and submit your
 contributions. Please read it carefully and let us know if it's not up-to date
 (or even better, submit a pull request with your corrections! :wink:).
 
 ## Pre-requisites
+
 ### Setup Docker image
+
 Due to the polyglot nature of `jsii`, the toolchain requirements are somewhat
 more complicated than for most projects. In order to locally develop `jsii`, you
 will need a number of tools.
@@ -19,37 +22,38 @@ our own CI/CD: the ["superchain" image][superchain] from.
 The image can be built for local usage, too:
 
 ```console
-$ IMAGE=superchain
-$ docker build -t ${IMAGE} -f superchain/Dockerfile .
+IMAGE=superchain
+docker build -t ${IMAGE} -f superchain/Dockerfile .
 ```
 
 In order to get an interactive shell within a Docker container using the
 *superchain* image you just built:
 
 ```console
-$ cd jsii # go to the root of the jsii repo
-$ docker run --rm --net=host -it -v $PWD:$PWD -w $PWD ${IMAGE}
+cd jsii # go to the root of the jsii repo
+docker run --rm --net=host -it -v $PWD:$PWD -w $PWD ${IMAGE}
 ```
 
 In the shell that pops up, the `npm run` commands in the following sections must
 be executed.
 
 ### Alternative: Manually install the toolchain
+
 The following tools need to be installed to develop on JSII locally. We recommend
 using the docker image from the above section, but if you wish to, you can install
 in your development environment.
 
 - [Node `18.0.0`] or later
 - [Yarn `1.19.1`] or later
 - An OpenJDK-8 distribution (e.g: [Oracle's OpenJDK8], [Amazon Corretto 8])
-  + [`maven >= 3.0.5`](https://maven.apache.org)
+  - [`maven >= 3.0.5`](https://maven.apache.org)
 - [.NET `6.0`] or later
-  + *Recommended:* [`mono >= 6`](https://www.mono-project.com)
+  - *Recommended:* [`mono >= 6`](https://www.mono-project.com)
 - [Python `3.8.10`] or later
-  + [`pip`](https://pip.pypa.io/en/stable/installing/)
-  + [`setuptools >= 38.6.0`](https://pypi.org/project/setuptools/)
-  + [`wheel`](https://pypi.org/project/wheel/)
-  + *Recommended:* [`twine`](https://pypi.org/project/twine/)
+  - [`pip`](https://pip.pypa.io/en/stable/installing/)
+  - [`setuptools >= 38.6.0`](https://pypi.org/project/setuptools/)
+  - [`wheel`](https://pypi.org/project/wheel/)
+  - *Recommended:* [`twine`](https://pypi.org/project/twine/)
 - [Go] `1.18` or newer
 
 [Node `18.0.0`]: https://nodejs.org/download/release/latest-v18.x/
@@ -61,6 +65,7 @@ in your development environment.
 [Go]: https://go.dev/dl/
 
 ## Getting Started
+
 ### Bootstrapping
 
 The project is managed as a [monorepo] using [lerna].
@@ -98,7 +103,7 @@ The `jsii-calc` and `@scope/*` packages are used to test expected brhavior from
 the compiler (note that the [aws/jsii-compiler](github.com/aws/jsii-compiler)
 repository as a separate copy of these under the `fixtures` directory), as well
 as downstream tooling (`jsii-pacmak`, `jsii-rosetta`, etc...). Each language
-runtime has its own test suite, within which is a _compliance_ suite that tests
+runtime has its own test suite, within which is a *compliance* suite that tests
 the same behaviors in all languages, and which should contain tests related to
 behavior that isn't strictly specific to the given language.
 
@@ -138,8 +143,8 @@ better:
   to wait for a debugger to attach before proceeding. This is useful to attach
   Node dev tools to the runtime as it starts in order to use its debugger.
 
-The [Visual Studio Code](https://code.visualstudio.com) _JavaScript Debug
-Terminal_ feature can be particularly useful paired with appropriate
+The [Visual Studio Code](https://code.visualstudio.com) *JavaScript Debug
+Terminal* feature can be particularly useful paired with appropriate
 `JSII_RUNTIME` setting to run arbitrary jsii programs, automatically attaching
 the VSCode debugger at startup. These terminals inject a specially crafted
 `NODE_OPTIONS` variable that allows the VSCode debugger to consistently attach
@@ -205,10 +210,10 @@ The runtime client library should be implemented as a module under
 
 The jsii runtime client library usually includes the following components:
 
-- Child process manager: responsible to start/stop the **@jsii/runtime** child
+- Child process manager: responsible to start/stop the __@jsii/runtime__ child
   process.
 - Protocol layer: implements the STDIN/STDOUT protocol that interacts with the
-  **@jsii/runtime**.
+  __@jsii/runtime__.
 - Proxy layer: includes base classes and serialization utilities to implement
   the generated proxy classes.
 
@@ -244,8 +249,8 @@ on [ECR Public Gallery](https://gallery.ecr.aws/jsii/superchain)
 ## Support for new Node Major versions
 
 When a new major version of node is released, we need to update the `@jsii/check-node` package.
-This package is responsible for identifiying which node version is being used by the current process,
-whether or not it is supported and tested, and produces appropriate warnings in case it isnt.
+This package is responsible for identifying which node version is being used by the current process,
+whether or not it is supported and tested, and produces appropriate warnings in case it isn't.
 
 > Note that `jsii` will execute on every node version, so "adding support" here only means supressing or showing
 > warnings that inform the user on the level of support it has.
@@ -258,4 +263,16 @@ whether or not it is supported and tested, and produces appropriate warnings in
 ### Useful Resources
 
 - [https://endoflife.date/nodejs](https://endoflife.date/nodejs)
-- [Adding support for node 22 PR](https://github.com/aws/jsii/pull/4489)
+- [Adding support for node 22 PR](https://github.com/aws/jsii/pull/4489)
+
+## Support for new `jsii-rosetta` versions
+
+When a new minor version of `jsii-rosetta` (modern) is released, we need to update the `jsii-pacmak` package.
+`jsii-pacmak` uses `jsii-rosetta` to transpile examples in documentation.
+Because every package can use its own version of jsii, TypeScript and jsii-rosetta, it is declared as a peer dependency.
+To ensure compatibility, we also have integration tests.
+
+### Adding a new `jsii-rosetta` version
+
+1. Add the new version to the `jsii-rosetta` peer dependency in [package.json](./packages/jsii-pacmak/package.json)
+2. Add the new version to the `pacmak-integration-test` matrix in the main build workflow in [main.yml](.github/workflows/main.yml)
diff --git a/gh-pages/content/overview/toolchain.md b/gh-pages/content/overview/toolchain.md
@@ -15,7 +15,6 @@
 | [jsii-rosetta1] | `1.x`   | [Maintenance] | Transpile code snippets (in docs) from TypeScript to jsii languages   |
 | [jsii-rosetta]  | `5.x`   | GA            | 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]   | *any*   | Community     | Generates markdown API documentation for jsii modules                 |
 
@@ -41,6 +40,5 @@
 [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
+[jsii-srcmak]: https://github.com/cdklabs/jsii-srcmak
+[jsii-docgen]: https://github.com/cdklabs/jsii-docgen
diff --git a/gh-pages/content/user-guides/language-support/index.md b/gh-pages/content/user-guides/language-support/index.md
@@ -103,7 +103,7 @@ possible to publish artifacts even when tests in the suite are failing. As soon
     contribute to this process by documenting a general architecture that should be implementable in any programming
     languages (and thus, abstracting away language specificities).
 
-## Building & Packaging
+## Building and Packaging
 
 The necessary toolchains should be added to he [`public.ecr.aws/jsii/superchain`] Docker image, so that the
 [`jsii-pacmak`] generation can be changed to support building ready to publish artifacts instead of just code.
@@ -115,10 +115,6 @@ PyPI, and **NuGet** packages were published with a pre-release version such as `
 Additionally, [`aws-delivlib`] needs to be augmented to support publishing artifacts to the language's package
 repository.
 
-!!! bug "Unimplemented"
-    The package publishing is being extracted from [`aws-delivlib`] into a standalone library, currently hosted at
-    [`eladb/jsii-release`](https://github.com/eladb/jsii-release).
-
 ## Documentation
 
 Before releasing the new language support to _Developer Preview_, basic documentation needs to be produced to explain
diff --git a/packages/@jsii/go-runtime/build-tools/package.sh b/packages/@jsii/go-runtime/build-tools/package.sh
@@ -7,6 +7,6 @@ rm -fr dist
 mkdir -p dist/go
 rsync -av jsii-runtime-go/* dist/go/
 
-# create a "version" file which is needed by jsii-release
+# create a "version" file which is needed by publib
 version=$(node -p "require('./package.json').version")
 echo ${version} > dist/go/version
diff --git a/packages/jsii-pacmak/package.json b/packages/jsii-pacmak/package.json
@@ -68,7 +68,7 @@
     "pyright": "^1.1.376"
   },
   "peerDependencies": {
-    "jsii-rosetta": "^0.0.0 || ~5.2.0 || ~5.3.0 || ~5.4.0"
+    "jsii-rosetta": "^0.0.0 || ~5.2.0 || ~5.3.0 || ~5.4.0 || ~5.5.0"
   },
   "keywords": [
     "jsii",
