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-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) 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.