From 3a12da49927d770b8126c10c0cf8ead8d0814c47 Mon Sep 17 00:00:00 2001 From: Freeman Date: Fri, 1 May 2026 14:04:31 +0100 Subject: [PATCH 1/2] docs: fix stale release instructions and mark superseded PR write-ups Two small cleanups after the v1.1.0 release debugging spiral: - AGENTS.md referenced the old "Release" workflow name and version-bump instructions. The workflow was renamed to "Publish" to match npm's Trusted Publisher registration. Update the instructions and add a note about the skip_bump input for re-publishing stalled versions. - Three PR write-ups in documentation/PULL_REQUESTS/ describe fixes that were later reverted or superseded. Prepend a "Superseded" banner to each with a forward-pointer to the PR that actually fixed the issue. Content preserved for historical context. --- AGENTS.md | 8 ++++++-- .../PULL_REQUESTS/2026-05-01-fix-release-corepack.md | 2 ++ .../PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md | 2 ++ .../PULL_REQUESTS/2026-05-01-fix-release-npm-upgrade.md | 2 ++ 4 files changed, 12 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 562f113..8b693ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,10 @@ Do NOT bump versions or publish locally. Use the GitHub Actions workflow: -1. Go to Actions > Release > Run workflow +1. Go to Actions > Publish > Run workflow 2. Select version bump type (patch/minor/major) -3. The workflow will bump version, push tags, create a GitHub release, and publish to npm automatically +3. The workflow will run tests, bump version, push tags, create a GitHub release, and publish to npm automatically + +### Republishing a stalled version + +If a previous run tagged the version and created the GitHub release but failed at the npm publish step (rare, usually infrastructure-related), re-run the workflow with the `skip_bump` input set to true. This will republish the current `package.json` version without bumping or re-tagging. diff --git a/documentation/PULL_REQUESTS/2026-05-01-fix-release-corepack.md b/documentation/PULL_REQUESTS/2026-05-01-fix-release-corepack.md index 798bdec..2ec9845 100644 --- a/documentation/PULL_REQUESTS/2026-05-01-fix-release-corepack.md +++ b/documentation/PULL_REQUESTS/2026-05-01-fix-release-corepack.md @@ -1,3 +1,5 @@ +> **⚠️ Superseded:** The corepack-based approach described here was reverted. The real root cause was unrelated — the npm Trusted Publisher was registered against the old workflow filename `publish.yml`, but the workflow had been renamed to `release.yml`. See [`2026-05-01-fix-release-node20.md`](./2026-05-01-fix-release-node20.md) for the fix that actually worked. Preserved for historical context. + ## Problem Our release pipeline is currently unable to publish new versions to npm. The step that upgrades the installed `npm` to a version new enough to use our secure authentication method fails with an internal error — not because the target version is wrong, but because the copy of `npm` preinstalled on our build server has corrupted dependencies and cannot install anything, including itself. diff --git a/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md b/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md index 079e84e..7516f62 100644 --- a/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md +++ b/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md @@ -1,3 +1,5 @@ +> **⚠️ Partially superseded:** The `skip_bump` input added here is still in use, but the `npm@11` version pin was later reverted to `npm@latest`. See [`2026-05-01-fix-release-node20.md`](./2026-05-01-fix-release-node20.md) for the complete fix. Preserved for historical context. + ## Problem The previous release workflow attempt reached the publish step but failed to authenticate with npm, even though everything upstream had completed successfully — tag created, GitHub release page live. The underlying cause was that the `npm` version shipped with the GitHub Actions runner is too old to use our secure publishing path. diff --git a/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-upgrade.md b/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-upgrade.md index 895dd65..6766922 100644 --- a/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-upgrade.md +++ b/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-upgrade.md @@ -1,3 +1,5 @@ +> **⚠️ Superseded:** This change was later reverted. The diagnosis here was incorrect — the `npm` upgrade step was actually necessary. See [`2026-05-01-fix-release-node20.md`](./2026-05-01-fix-release-node20.md) for the fix that actually worked. Preserved for historical context. + ## Problem Our release workflow failed on the very first run after introducing CI — not on any of our changes, but on an infrastructure step that was already there: an attempt to upgrade npm that no longer works on the current GitHub Actions runner. Tests passed, so nothing broken was shipped, but the version bump and publish never happened. From 98719e2d81103e179b5d93b14e3c1b3df7fed313 Mon Sep 17 00:00:00 2001 From: Freeman Date: Fri, 1 May 2026 14:04:41 +0100 Subject: [PATCH 2/2] docs: add PR write-up for Clean up stale docs and add superseded banners to old PR write-ups --- .../2026-05-01-cleanup-red-herrings.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 documentation/PULL_REQUESTS/2026-05-01-cleanup-red-herrings.md diff --git a/documentation/PULL_REQUESTS/2026-05-01-cleanup-red-herrings.md b/documentation/PULL_REQUESTS/2026-05-01-cleanup-red-herrings.md new file mode 100644 index 0000000..684437e --- /dev/null +++ b/documentation/PULL_REQUESTS/2026-05-01-cleanup-red-herrings.md @@ -0,0 +1,19 @@ +## Problem + +After the debugging spiral that preceded the `v1.1.0` release, a review surfaced two places on `main` where the documentation no longer matches reality: + +1. Our release instructions still point to a workflow name that no longer exists (the file was renamed during the fix). +2. Three of the PR write-ups from the debugging spiral describe fixes that didn't work or were later reverted, with no pointer to the PR that actually fixed the issue. A future reader finding them in isolation could easily be misled. + +## Solution + +Update the release instructions to match the current workflow name, and add a "Superseded" banner to each of the three misleading PR write-ups with a link to the real fix. Historical content is preserved in full. + +## Impact + +No behavior changes. Anyone reading `AGENTS.md` or the old PR write-ups now gets accurate guidance. + +# Credits + +- Nabs (Architect) +- JENA (Lead Developer)