v1.0.0 release checklist: ordering prerequisites, breaking-change notes, and post-tag verification

Context

#198 declares 1.0.0 and adds a versioning / schema-stability policy. Cutting the tag has prerequisites that span several PRs and one unresolved infrastructure issue, and getting the order wrong produces a release that is broken in ways CI will not catch. This is the checklist.

Verified current state

• npm: the package is @o1-labs/mina-archive-node-graphql. npm view … versions returns only 0.0.6; dist-tags is { latest: '0.0.6' }. v0.0.7–v0.0.9 were tagged but never published.
• #208 is still open — npm trusted publishing was never configured, so the publish job fails ENEEDAUTH.
• GHCR: o1-labs/archive-node-api has 0.0.1-test, latest, 0.0, 0, 0.0.1, 0.0.2, 0.0.4, 0.0.5, 0.0.8, 0.0.6, 0.0.9. No 1.0.0.
• Docker publishing works even though npm's does not — build.yaml pushes GHCR tags on refs/tags/v* and 0.0.9 is present. The two halves of the pipeline are in different states.

Blocking prerequisite

• #208 must be resolved before v1.0.0 is pushed. Otherwise the publish job fails ENEEDAUTH exactly as it did for v0.0.9, and 1.0.0 joins 0.0.7–0.0.9 as a tag with no package behind it.

  Note this no longer blocks merging #198 — its docs now correctly condition the claim on "once npm trusted publishing is configured". It blocks the tag.

Content prerequisites — cut the tag only from a main that already contains

• #187 — /readiness. #196's reference manifests configure a readiness probe against this path; on a 0.0.x image it 404s, no pod goes Ready, and the Service loses every endpoint.
• #191 — /metrics. #196 sets ENABLE_METRICS: 'true' and annotates pods for Prometheus scraping.
• #188 — SHUTDOWN_TIMEOUT_MS, which #196's manifest sets to 10000 and sizes its terminationGracePeriodSeconds: 45 around.
• #184 — the CORS default change that CORS_ORIGIN: '*' in the manifest exists to counteract.
• #185 — TRUST_PROXY / RATE_LIMIT_MAX, both set explicitly in the manifest.

If the tag is cut early, #196's manifests probe endpoints the image does not serve and set env vars it ignores — and the failure presents as pods that never become Ready, not as an obvious version mismatch.

• #186 must be unblocked and merged (it currently has changes requested for stating that TRUST_PROXY defaults to 0, when #185 ships no default and disables rate limiting entirely while it is unset).

Release-note content — these are breaking and must be called out

• CORS default (#184) — browser clients break unless CORS_ORIGIN is set. mina-explorer calls this API directly and cross-origin from the browser, so this is a hard operational prerequisite for that consumer, not a theoretical one.
• Rate limiting (#185) — default-on once TRUST_PROXY is set; request-rejecting behaviour that did not previously exist.
• Minimum Node runtime (#194) — engines: ">=22.12.0", plus the Docker base image and CI Node version.
• ENABLE_INTROSPECTION="false" now actually means off (#193). On main, any non-empty value enables introspection, so any deployment that set false has been serving introspection this whole time. This is a behaviour change in the safe direction, but it is a change.
• ENABLE_GRAPHIQL=1 / =yes now enable GraphiQL (#193) — previously only the literal string true counted. An exposure change.
• Query-cost limits (#183) — depth 12 / aliases 15 / tokens 1000 / cost 5000, with a documented depth floor of 8.

Post-tag verification

• npm view @o1-labs/mina-archive-node-graphql dist-tags shows latest: 1.0.0
• docker pull ghcr.io/o1-labs/archive-node-api:1.0.0 succeeds
• docs/getting-started.md's docker pull …:1.0.0 command works (it is currently written against a tag that does not exist yet)
• A pod from the 1.0.0 image passes #196's readiness probe against /readiness

Known doc defect to fix before or with the tag

#198's release procedure reads:

git tag v1.0.0 && git push --follow-tags

This does not work. git tag without -a/-s creates a lightweight tag, and git push --follow-tags pushes only annotated tags — so nothing is pushed and no release fires. Fix:

git tag -a v1.0.0 -m 'v1.0.0'   # annotated: --follow-tags ignores lightweight tags
git push --follow-tags

(The npm version path used for subsequent releases is unaffected — npm creates annotated tags.)

Related

• #208 (blocking), #198 (declares the version), #196 (manifests that pin :1.0.0), #211 (merge order for the batch)

Start with #208, #198's release procedure, build.yaml, and docs/getting-started.md, then verify the prerequisite issues and #196's manifests. Done means the annotated v1.0.0 tag triggers publishing, npm and GHCR expose 1.0.0, the documented Docker pull works, and a pod passes the /readiness probe.