Verified while cutting 0.2.2 (#301) on main @ af09b7c / dev @ ffc828c.
Summary
Bumping the release version means editing the same scattered set of hardcoded strings by hand. Miss one and the failure arrives late: some spots break CI, one breaks the GitHub release after npm has already published.
The surface, as of 0.2.2
Derived from package.json (safe, no action):
- nothing. Every version reference below is a literal.
Must be edited by hand:
| Where |
What |
17 package.json files |
version plus every exact @the-open-engine/* internal pin (check-workspace.mjs:366, :472 enforce this) |
Cargo.toml |
workspace version |
packages/opcore-graph-core-*/metadata.json × 3 |
artifactVersion |
scripts/check-workspace.mjs:21 |
const releaseVersion = "…" |
scripts/release-dry-run.mjs:15 |
const releaseVersion = "…" |
scripts/release-publish.mjs:9 |
valueAfter("--version") ?? "…" |
.github/workflows/release.yml:29, :100 |
RELEASE_VERSION, OPCORE_CONFIRM_PUBLISH |
runtime-info.ts, timing.ts, graph/src/serve.ts, graph/src/artifact.ts, asp-provider/src/protocol.ts |
version fallbacks and message literals |
AGENTS.md:86, CLAUDE.md:86 |
the prose naming the published version |
docs/release/v<version>.md |
must be created, see below |
| 5 test assertions |
opcore-facade (--version output, runtimeInfo.version), native-packaging-policy:128, graph-core-artifact:28, asp-provider:909 |
Traps worth calling out:
tests/ contains roughly 50 other 0.2.1 strings that must not move: sample Cargo.toml versions, schema-contract payloads, "0.2.1-test" fake host versions. A blanket find-and-replace corrupts fixtures.
packages/opcore/src/try.ts:227 writes version = "0.2.1" into a generated sample repo. Also not ours.
release.yml:111 hard-errors with Missing release notes if docs/release/v<version>.md is absent — but that check runs at line 110, after npm run release:publish at line 98. So forgetting the notes file publishes to npm and then fails the GitHub release, leaving a half-done release that cannot be cleanly retried.
Suggested fix
Either derive the version in one place, or script the bump:
- Have
check-workspace.mjs, release-dry-run.mjs, and release-publish.mjs read the root package.json version instead of each holding a literal.
- Have the runtime constants fall back to the packaged
package.json rather than an inline string (runtime-info.ts already does this and only needs the literal fallback updated).
- Move the release-notes existence check to the top of the release job, before publish, so a missing file fails closed instead of half-publishing.
- Failing all that, a
scripts/bump-version.mjs that edits the table above and a CI check that no stale version literal survives.
Item 3 is worth doing on its own even if the rest waits, since it is the one that fails after an irreversible npm publish.
Verified while cutting
0.2.2(#301) onmain @ af09b7c/dev @ ffc828c.Summary
Bumping the release version means editing the same scattered set of hardcoded strings by hand. Miss one and the failure arrives late: some spots break CI, one breaks the GitHub release after npm has already published.
The surface, as of 0.2.2
Derived from
package.json(safe, no action):Must be edited by hand:
package.jsonfilesversionplus every exact@the-open-engine/*internal pin (check-workspace.mjs:366,:472enforce this)Cargo.tomlversionpackages/opcore-graph-core-*/metadata.json× 3artifactVersionscripts/check-workspace.mjs:21const releaseVersion = "…"scripts/release-dry-run.mjs:15const releaseVersion = "…"scripts/release-publish.mjs:9valueAfter("--version") ?? "…".github/workflows/release.yml:29, :100RELEASE_VERSION,OPCORE_CONFIRM_PUBLISHruntime-info.ts,timing.ts,graph/src/serve.ts,graph/src/artifact.ts,asp-provider/src/protocol.tsAGENTS.md:86,CLAUDE.md:86docs/release/v<version>.mdopcore-facade(--versionoutput,runtimeInfo.version),native-packaging-policy:128,graph-core-artifact:28,asp-provider:909Traps worth calling out:
tests/contains roughly 50 other0.2.1strings that must not move: sampleCargo.tomlversions, schema-contract payloads,"0.2.1-test"fake host versions. A blanket find-and-replace corrupts fixtures.packages/opcore/src/try.ts:227writesversion = "0.2.1"into a generated sample repo. Also not ours.release.yml:111hard-errors withMissing release notesifdocs/release/v<version>.mdis absent — but that check runs at line 110, afternpm run release:publishat line 98. So forgetting the notes file publishes to npm and then fails the GitHub release, leaving a half-done release that cannot be cleanly retried.Suggested fix
Either derive the version in one place, or script the bump:
check-workspace.mjs,release-dry-run.mjs, andrelease-publish.mjsread the rootpackage.jsonversion instead of each holding a literal.package.jsonrather than an inline string (runtime-info.tsalready does this and only needs the literal fallback updated).scripts/bump-version.mjsthat edits the table above and a CI check that no stale version literal survives.Item 3 is worth doing on its own even if the rest waits, since it is the one that fails after an irreversible npm publish.