From a7a59a2637a9860b74361378b943e652ff07050a Mon Sep 17 00:00:00 2001 From: woksin Date: Tue, 29 Sep 2026 19:48:13 +0200 Subject: [PATCH 1/4] Document Components 3 with PrimeReact 11.2 and the 3.x release path Troubleshooting explains the Components 3 build failure with PrimeReact 11.2 and its remedies (#375). release.md describes publishing 3.x maintenance releases from support/3.x under the v3-lts dist-tag (#379) --- Documentation/troubleshooting.md | 4 ++++ release.md | 22 ++++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/Documentation/troubleshooting.md b/Documentation/troubleshooting.md index 45bd26df..f46acacb 100644 --- a/Documentation/troubleshooting.md +++ b/Documentation/troubleshooting.md @@ -44,6 +44,10 @@ The public adapters implement the declared presentation slots rather than replac Use the [UI foundation capability matrix](ui-foundation.md#capability-matrix) to check the server-rendering boundary for the component profile. For a custom portal container, resolve `document` inside `overlayEnvironment.getContainer` and return `null` when it is unavailable, as shown in [Choose an overlay container](Common/cratis-components-provider.md#choose-an-overlay-container). +## Components 3 fails to build after updating PrimeReact to 11.2 + +`@cratis/components` 3.x imports `@primereact/styles/password`, which PrimeReact 11.2.0 renamed to `inputpassword`. Its peer range still accepts 11.2.0, so the install succeeds and then a bundler that follows package `exports`, such as Vite, fails with `"styles" is not exported by ... @primereact/styles/password`. Keep `primereact` and every `@primereact/*` package at 11.1.x while you stay on Components 3, or move to Components 4, which does not depend on PrimeReact; see [Migrating from 3 to 4](Migration/3-to-4.md). The PrimeReact 11 renderer adapter for Components 4 is tested against 11.2.0. + ## See also For generated proxies, command authorization, command validation, and Arc request behavior, use [Arc troubleshooting](/arc/troubleshooting/). diff --git a/release.md b/release.md index 5586f1a8..29c90d75 100644 --- a/release.md +++ b/release.md @@ -59,6 +59,28 @@ A brand-new npm package must receive a one-time authenticated bootstrap publicat publishing can be configured; do not begin a multi-package release until all package records and trusted publishers are ready. +## Components 3 maintenance releases + +Components 3 is in maintenance support and is released from the `support/3.x` branch, never from +`main`. Land a fix there through a pull request, then dispatch `publish.yml` on `support/3.x` with +the exact 3.x version. That workflow: + +- refuses to run anywhere but `support/3.x`, or for a version that is not a new 3.x version; +- builds, lints, and tests before publishing; +- publishes `@cratis/components` and `@cratis/eslint-plugin-components` under the `v3-lts` + dist-tag. `publish-version` refuses to publish without a non-`latest` tag, so npm `latest` stays + on the current major. Applications depending on `^3.x` still receive the release through their + range; +- verifies that the packages reached the registry under `v3-lts` and that `latest` did not move; + and +- pushes a plain `v3.x.y` git tag and creates no GitHub release. The release action on `main` + computes its next version from the latest GitHub release, so a 3.x release there would derail + the next 4.x version. + +If a publish ever moves `latest` to 3.x, restore it with an npm account that can manage the +package: `npm dist-tag add @cratis/components@ latest`, and the same for +`@cratis/eslint-plugin-components`. + ## Release evidence and verification `.github/workflows/javascript-build.yml` generates retained archives, SHA-256/SHA-512 manifests, From 40c7fe866947d0daf67b604609164bb723055a31 Mon Sep 17 00:00:00 2001 From: woksin Date: Tue, 29 Sep 2026 20:04:56 +0200 Subject: [PATCH 2/4] Describe dispatching, resuming and tag recovery for 3.x releases Name the exact dispatch command and the danger of dispatching on main, explain that re-runs continue a partial publish, correct why 3.x creates no GitHub release, and add the manual tag recovery (#379) --- release.md | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/release.md b/release.md index 29c90d75..d0c98e3e 100644 --- a/release.md +++ b/release.md @@ -62,23 +62,36 @@ trusted publishers are ready. ## Components 3 maintenance releases Components 3 is in maintenance support and is released from the `support/3.x` branch, never from -`main`. Land a fix there through a pull request, then dispatch `publish.yml` on `support/3.x` with -the exact 3.x version. That workflow: +`main`. Land a fix there through a pull request, then dispatch the support branch's `publish.yml` +with the exact 3.x version: + +```bash +gh workflow run publish.yml --ref support/3.x -f version=3.x.y +``` + +In the GitHub form, choose **Use workflow from: support/3.x**. Dispatching on `main` runs the +4.x publish workflow instead, which would create a `v3.x.y` GitHub release on `main`. + +The support branch's workflow: - refuses to run anywhere but `support/3.x`, or for a version that is not a new 3.x version; -- builds, lints, and tests before publishing; +- builds, lints, and tests before publishing, in a job that cannot write to the repository; - publishes `@cratis/components` and `@cratis/eslint-plugin-components` under the `v3-lts` dist-tag. `publish-version` refuses to publish without a non-`latest` tag, so npm `latest` stays on the current major. Applications depending on `^3.x` still receive the release through their range; -- verifies that the packages reached the registry under `v3-lts` and that `latest` did not move; +- skips packages already on the registry at that version, so re-running a failed run continues + where it stopped; +- verifies that both packages reached the registry under `v3-lts` and that `latest` did not move; and -- pushes a plain `v3.x.y` git tag and creates no GitHub release. The release action on `main` - computes its next version from the latest GitHub release, so a 3.x release there would derail - the next 4.x version. - -If a publish ever moves `latest` to 3.x, restore it with an npm account that can manage the -package: `npm dist-tag add @cratis/components@ latest`, and the same for +- then pushes a plain `v3.x.y` git tag. It creates no GitHub release, so GitHub never marks a 3.x + release as the repository's latest release. The release action on `main` versions from the + highest release, so 3.x tags do not affect it. + +If both packages show the version under `v3-lts` but the tag was never pushed, push it at the +dispatched commit: `git tag v3.x.y && git push origin v3.x.y`. If a publish ever moves +`latest` to 3.x, restore it with an npm account that can manage the package: +`npm dist-tag add @cratis/components@ latest`, and the same for `@cratis/eslint-plugin-components`. ## Release evidence and verification From 415e25e558045f3cc3fc79ae3df9ad705fc23adf Mon Sep 17 00:00:00 2001 From: woksin Date: Tue, 29 Sep 2026 20:05:14 +0200 Subject: [PATCH 3/4] Refuse to dispatch a release of an older major on main A 3.x version dispatched on main would create its GitHub release there. Older majors are released from their support branch (#379) --- .github/workflows/publish.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 15a7dbd3..62f7144d 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -58,6 +58,20 @@ jobs: - name: Checkout code uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + # Older majors are released from their support branch (see release.md). A version from + # an older major dispatched here would create its GitHub release on main. + - name: Refuse a dispatched version from an older major + if: github.event_name == 'workflow_dispatch' + env: + VERSION: ${{ github.event.inputs.version }} + run: | + current_major=$(node -p "require('./Source/package.json').version.split('.')[0]") + requested_major="${VERSION%%.*}" + if [[ "$VERSION" != "0.0.0" && "$requested_major" -lt "$current_major" ]]; then + echo "::error::$VERSION belongs to an older major; dispatch publish.yml on its support branch instead." + exit 1 + fi + - name: Release id: release uses: cratis/release-action@f5fc6db6adbb4db6e6c4548cd7addfc924426e69 # v1 From deffbea24c72e00bb3a09ad8fced7a6881411ccd Mon Sep 17 00:00:00 2001 From: woksin Date: Tue, 29 Sep 2026 20:10:10 +0200 Subject: [PATCH 4/4] Validate the dispatched version before comparing majors, and update the docs The older-major guard checks the version format before any arithmetic, so a crafted input cannot run as a command, and fails if the current major cannot be read. release.md says main refuses an older major, and troubleshooting names the 3.x versions that accept PrimeReact 11.2 (#375, #379) --- .github/workflows/publish.yml | 14 ++++++++++++-- Documentation/troubleshooting.md | 2 +- release.md | 2 +- 3 files changed, 14 insertions(+), 4 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 62f7144d..68ac544c 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -65,9 +65,19 @@ jobs: env: VERSION: ${{ github.event.inputs.version }} run: | + set -euo pipefail + [[ "$VERSION" == "0.0.0" ]] && exit 0 + if [[ ! "$VERSION" =~ ^([0-9]+)\.[0-9]+\.[0-9]+$ ]]; then + echo "::error::'$VERSION' is not a version." + exit 1 + fi + requested_major="${BASH_REMATCH[1]}" current_major=$(node -p "require('./Source/package.json').version.split('.')[0]") - requested_major="${VERSION%%.*}" - if [[ "$VERSION" != "0.0.0" && "$requested_major" -lt "$current_major" ]]; then + if [[ ! "$current_major" =~ ^[0-9]+$ ]]; then + echo "::error::Could not read the current major from Source/package.json." + exit 1 + fi + if (( 10#$requested_major < 10#$current_major )); then echo "::error::$VERSION belongs to an older major; dispatch publish.yml on its support branch instead." exit 1 fi diff --git a/Documentation/troubleshooting.md b/Documentation/troubleshooting.md index f46acacb..f62e3ce8 100644 --- a/Documentation/troubleshooting.md +++ b/Documentation/troubleshooting.md @@ -46,7 +46,7 @@ Use the [UI foundation capability matrix](ui-foundation.md#capability-matrix) to ## Components 3 fails to build after updating PrimeReact to 11.2 -`@cratis/components` 3.x imports `@primereact/styles/password`, which PrimeReact 11.2.0 renamed to `inputpassword`. Its peer range still accepts 11.2.0, so the install succeeds and then a bundler that follows package `exports`, such as Vite, fails with `"styles" is not exported by ... @primereact/styles/password`. Keep `primereact` and every `@primereact/*` package at 11.1.x while you stay on Components 3, or move to Components 4, which does not depend on PrimeReact; see [Migrating from 3 to 4](Migration/3-to-4.md). The PrimeReact 11 renderer adapter for Components 4 is tested against 11.2.0. +`@cratis/components` 3.x imports `@primereact/styles/password`, which PrimeReact 11.2.0 renamed to `inputpassword`. Components 3.6.1 and earlier declare PrimeReact `^11.0.0`, so the install succeeds and then a bundler that follows package `exports`, such as Vite, fails with `"styles" is not exported by ... @primereact/styles/password`. Later 3.x maintenance releases limit PrimeReact to versions below 11.2.0, so the package manager reports the mismatch instead. Keep `primereact` and every `@primereact/*` package at 11.1.x while you stay on Components 3, or move to Components 4, which does not depend on PrimeReact; see [Migrating from 3 to 4](Migration/3-to-4.md). The PrimeReact 11 renderer adapter for Components 4 is tested against 11.2.0. ## See also diff --git a/release.md b/release.md index d0c98e3e..03089037 100644 --- a/release.md +++ b/release.md @@ -70,7 +70,7 @@ gh workflow run publish.yml --ref support/3.x -f version=3.x.y ``` In the GitHub form, choose **Use workflow from: support/3.x**. Dispatching on `main` runs the -4.x publish workflow instead, which would create a `v3.x.y` GitHub release on `main`. +4.x publish workflow, which refuses a version from an older major. The support branch's workflow: