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

[SanabriaRusso]

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.
• npm publishing from CI has never worked: trusted publisher is not configured (v0.0.9 tagged but unpublished) #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

• npm publishing from CI has never worked: trusted publisher is not configured (v0.0.9 tagged but unpublished) #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 P2: Declare 1.0.0 + versioning & schema stability policy (#178) #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

• P1: Add readiness probe distinct from liveness (#169) #187 — /readiness. P2: Reference deployment manifests — k8s + prod Compose (#179) #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.
• P1: Expose Prometheus metrics at /metrics (#173) #191 — /metrics. P2: Reference deployment manifests — k8s + prod Compose (#179) #196 sets ENABLE_METRICS: 'true' and annotates pods for Prometheus scraping.
• P1: Graceful shutdown — drain, flush traces, uncaught handlers (#170) #188 — SHUTDOWN_TIMEOUT_MS, which P2: Reference deployment manifests — k8s + prod Compose (#179) #196's manifest sets to 10000 and sizes its terminationGracePeriodSeconds: 45 around.
• P0: Secure CORS default instead of '*' (#167) #184 — the CORS default change that CORS_ORIGIN: '*' in the manifest exists to counteract.
• P0: Add per-IP request rate limiting (#166) #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.

• P0: Add security & deployment hardening guide (#168) #186 must be unblocked and merged (it currently has changes requested for stating that TRUST_PROXY defaults to 0, when P0: Add per-IP request rate limiting (#166) #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 (P0: Secure CORS default instead of '*' (#167) #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 (P0: Add per-IP request rate limiting (#166) #185) — default-on once TRUST_PROXY is set; request-rejecting behaviour that did not previously exist.
• Minimum Node runtime (P1: Upgrade to graphql-yoga 5 and Node 22 LTS (#176) #194) — engines: ">=22.12.0", plus the Docker base image and CI Node version.
• ENABLE_INTROSPECTION="false" now actually means off (P1: Validate config at startup + fix boolean env parsing (#174, #74) #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 (P1: Validate config at startup + fix boolean env parsing (#174, #74) #193) — previously only the literal string true counted. An exposure change.
• Query-cost limits (P0: Add GraphQL query-cost controls via graphql-armor (#164) #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 P2: Reference deployment manifests — k8s + prod Compose (#179) #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

• npm publishing from CI has never worked: trusted publisher is not configured (v0.0.9 tagged but unpublished) #208 (blocking), P2: Declare 1.0.0 + versioning & schema stability policy (#178) #198 (declares the version), P2: Reference deployment manifests — k8s + prod Compose (#179) #196 (manifests that pin :1.0.0), Merge order and three silent conflict hazards across the production-readiness PR batch #211 (merge order for the batch)