From 592f6e195a4b92374e753025ad73a7decf1ea38f Mon Sep 17 00:00:00 2001 From: dkijania Date: Wed, 7 Oct 2026 14:29:08 +0200 Subject: [PATCH 1/3] release: 2.0.0, one major with the client SDKs Schema 2.0 has no breaking change against 1.0; the major aligns this server with the SDKs, which need one for their own API. --- docs/versioning.md | 38 ++++++++++++++++++++++++++++++-------- package-lock.json | 4 ++-- package.json | 2 +- src/schema-version.ts | 5 +++-- 4 files changed, 36 insertions(+), 13 deletions(-) diff --git a/docs/versioning.md b/docs/versioning.md index 4df01d5..71c37ba 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -106,7 +106,7 @@ We prefer deprecation over removal: 1. Mark schema elements with the `@deprecated(reason: "…")` directive, pointing to the replacement and planned removal target, for example - `"Use X. Removed in 2.0.0, no earlier than 2026-11-15."`. + `"Use X. Removed in 3.0.0, no earlier than 2027-03-01."`. 2. Announce the deprecation in the GitHub release notes for the minor that introduces it. The 90-day clock starts when that release is published. 3. Keep the deprecated element working for **at least one minor release and 90 @@ -186,11 +186,15 @@ package version. } ``` -The server answers `"1.1"` today. Schema 1.1 is the schema that the 1.0.x -releases shipped (1.0), plus two additive changes: the `schemaVersion` query -itself and the `zkappCommands` query with its types. `zkappCommands` is off by -default (`ENABLE_ZKAPP_COMMANDS_QUERY`), but it is part of the contract, so it -moves the MINOR. +The server answers `"2.0"` today. Schema 2.0 has no breaking change against +schema 1.0, which the 1.0.x releases shipped; see "One major across the server +and the SDKs" below for why it is a major. Its changes against 1.0: + +- the `schemaVersion` query itself; +- the `zkappCommands` query and its types, off by default + (`ENABLE_ZKAPP_COMMANDS_QUERY`) but part of the contract; +- non-null elements on eight list positions that never carried a null + (`[T]!` → `[T!]!`), which only strengthens the guarantee. - The **package** version describes this server: its flags, its defaults, its behaviour. The list of breaking changes above is about that. @@ -203,8 +207,26 @@ a default or a flag without touching the contract, and a schema can gain a field without the server's own surface changing. The client SDKs pin the schema version they were built against and compare it -with what `schemaVersion` reports. That is why their package versions do not -track this repository's, and do not track Mina's either — see below. +with what `schemaVersion` reports. + +### One major across the server and the SDKs + +This package, its schema, and the three client SDKs +([JS](https://github.com/o1-labs/mina-archive-sdk-js), +[Go](https://github.com/o1-labs/mina-archive-sdk-go), +[Rust](https://github.com/o1-labs/mina-archive-sdk-rust)) share one MAJOR. +**Same major means compatible.** A higher server minor only adds what the SDK +does not know about yet. + +When any of them takes a major, all of them do, even those with no breaking +change of their own. Semver allows a major without a break; it forbids only a +break without a major. Minors and patches stay independent. + +2.0.0 is the first such release: the SDKs needed a major for changes to their +own API, and this server and its schema took one to match. A 1.0.x client +keeps working against it. + +Mina versions are separate — see below. `schemaVersion` is served even when `ENABLED_QUERIES` restricts the data queries. A compatibility check a deployment can switch off would leave clients diff --git a/package-lock.json b/package-lock.json index fffe18a..02a1cd8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@o1-labs/mina-archive-node-graphql", - "version": "1.0.1", + "version": "2.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@o1-labs/mina-archive-node-graphql", - "version": "1.0.1", + "version": "2.0.0", "license": "Apache-2.0", "dependencies": { "@envelop/core": "^5.5.1", diff --git a/package.json b/package.json index bd06949..c3b8a9d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@o1-labs/mina-archive-node-graphql", - "version": "1.0.1", + "version": "2.0.0", "description": "A NodeJS GraphQL server for exposing Mina Protocol archive node data for o1js/zkApps", "repository": { "type": "git", diff --git a/src/schema-version.ts b/src/schema-version.ts index 2fd75c8..f8abd89 100644 --- a/src/schema-version.ts +++ b/src/schema-version.ts @@ -18,6 +18,7 @@ * same major keeps working. * - **MAJOR** for a change that can break a client: a removed or renamed field, * a narrowed type, an argument that becomes required, or a field that becomes - * nullable when clients were entitled to assume it was not. + * nullable when clients were entitled to assume it was not. Also when the + * package or the SDKs take a major: they all share one (docs/versioning.md). */ -export const SCHEMA_VERSION = '1.1'; +export const SCHEMA_VERSION = '2.0'; From d233bffc10797afc2e2c79b1944c8a0e02d3ae30 Mon Sep 17 00:00:00 2001 From: dkijania Date: Thu, 8 Oct 2026 11:28:59 +0200 Subject: [PATCH 2/3] docs: upgrade notes for 2.0.0, tag-based releases, alignment major --- docs/runbook.md | 2 +- docs/versioning.md | 67 ++++++++++++++++++++++++++++++++-------------- 2 files changed, 48 insertions(+), 21 deletions(-) diff --git a/docs/runbook.md b/docs/runbook.md index 0770b00..fcbf9be 100644 --- a/docs/runbook.md +++ b/docs/runbook.md @@ -104,7 +104,7 @@ Recovery semantics to expect: - Rolling update; `terminationGracePeriodSeconds: 30` lets in-flight requests drain (the app shuts down gracefully on SIGTERM and flushes traces). - Readiness gates traffic to new pods until they can reach the DB. -- Roll back within the 1.0.x line — the service is stateless and carries no +- Roll back to any 1.0.0 or later image — the service is stateless and carries no migrations. Do **not** roll back to a 0.0.x image while readiness targets `/readiness`: that path 404s, no pod goes Ready, and the Service loses all endpoints. diff --git a/docs/versioning.md b/docs/versioning.md index 71c37ba..cfc8110 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -9,7 +9,9 @@ public contract. Given `MAJOR.MINOR.PATCH`: - **MAJOR** — a backwards-incompatible change to the public contract (see - "Breaking changes" below). Consumers may need to update queries or config. + "Breaking changes" below), or an alignment major shared with the client SDKs + (see "One major across the server and the SDKs"). Release notes say which; + an alignment major needs no consumer action. - **MINOR** — backwards-compatible additions: new schema fields/types/arguments, new optional config, new endpoints. Existing queries keep working. - **PATCH** — backwards-compatible bug fixes and internal changes. @@ -124,16 +126,20 @@ reviewed decision that must be paired with a major version bump. ## Releasing -Releases are cut from `main` by a maintainer: +Releases are cut in two steps: -```sh -npm version # bumps package.json + creates a git tag -git push --follow-tags # tag push triggers the publish pipeline -``` +1. A release PR bumps `package.json`/`package-lock.json` (and + `src/schema-version.ts` if the schema moved) and merges to `main`. +2. A maintainer tags that merge commit; the tag push triggers the publish + pipeline: + + ```sh + git tag v$(node -p "require('./package.json').version") + git push origin v + ``` -For the initial `1.0.0` release only, `package.json` on `main` already carries -the version to release. Tag it directly (`git tag v1.0.0 && git push ---follow-tags`) rather than running `npm version`, which would bump past it. +Do not run `npm version` on `main`: `package.json` already carries the version +being released, and `npm version` would bump past it. CI then builds and publishes the npm package (with provenance, once npm trusted publishing is configured for this repository) and the Docker images. Choose the @@ -159,21 +165,40 @@ registry logins and `npm publish`. Changing the step order, or reintroducing a stored credential, undoes both properties — see the ordering comment at the top of the job. -## Migrating from npm `0.0.6` +## Upgrading to 2.0.0 + +npm never received 1.0.x (only `0.0.6` is published), so npm consumers go +straight from `0.0.6` to `2.0.0`: apply both lists below. Container users on +1.0.0 need only the second. -Tags `0.0.7` through `0.0.9` existed in git but were not published to npm, so -npm consumers should treat `1.0.0` as an upgrade from `0.0.6`. Review these -operator-visible changes before rolling out: +### From `0.0.6` (changes that shipped in git tag 1.0.0) - Browser deployments must set `CORS_ORIGIN` deliberately. - Rate limiting is enabled and depends on the correct `TRUST_PROXY` hop count. -- The supported Node.js runtime moves to Node 22.12 (`engines`); the 1.0.x - container image runs Node 22. +- The supported Node.js runtime moves to Node 22.12 (`engines`). - Boolean environment variables reject junk values instead of relying on JavaScript truthiness. - `actions` result semantics include correctness fixes called out in the release notes. +### From 1.0.0 + +2.0.0 is an alignment major (see "One major across the server and the SDKs"): +no query that worked against 1.0.0 changes its result shape. Review: + +- The container image runs Node 24 (LTS) and is published for linux/amd64 and + linux/arm64. `engines` is unchanged (`>=22.12.0`). +- License: Apache-2.0 (was ISC). +- New query `schemaVersion`, always served, even when `ENABLED_QUERIES` + restricts the data queries. Listing it in `ENABLED_QUERIES` is accepted. +- New query `zkappCommands`, off unless `ENABLE_ZKAPP_COMMANDS_QUERY=true`; + bounded by `ZKAPP_COMMAND_RANGE_SIZE` (1000) and + `ZKAPP_COMMAND_ACCOUNT_UPDATE_LIMIT` (5000). +- `ENABLED_QUERIES` now accepts `verificationKeyUpdates` (1.0.0 failed startup + on it) and `zkappCommands`. +- Eight list positions declare non-null elements (`[T]` → `[T!]`). Responses + are unchanged; codegen'd clients see stricter element types. + ## Schema version `schema.graphql` carries its own `MAJOR.MINOR` version, served by the @@ -194,17 +219,19 @@ and the SDKs" below for why it is a major. Its changes against 1.0: - the `zkappCommands` query and its types, off by default (`ENABLE_ZKAPP_COMMANDS_QUERY`) but part of the contract; - non-null elements on eight list positions that never carried a null - (`[T]!` → `[T!]!`), which only strengthens the guarantee. + (`[T]` → `[T!]`), which only strengthens the guarantee. - The **package** version describes this server: its flags, its defaults, its behaviour. The list of breaking changes above is about that. - The **schema** version describes only what a client codes against: the types, fields and arguments in `schema.graphql`. Its MINOR moves on an additive - change, its MAJOR on one that can break a client. + change, its MAJOR on one that can break a client or on an alignment major + shared with the SDKs. -The two move independently, and that is deliberate. A server release can change -a default or a flag without touching the contract, and a schema can gain a field -without the server's own surface changing. +Their MINOR and PATCH move independently, and that is deliberate; the MAJOR is +shared (see "One major across the server and the SDKs"). A server release can +change a default or a flag without touching the contract, and a schema can gain +a field without the server's own surface changing. The client SDKs pin the schema version they were built against and compare it with what `schemaVersion` reports. From 07f178611cea6a7aa5c1764aa261896f23a29d42 Mon Sep 17 00:00:00 2001 From: dkijania Date: Fri, 9 Oct 2026 21:58:00 +0200 Subject: [PATCH 3/3] docs: point README releasing at versioning.md; tag from the merge commit --- README.md | 13 ++++--------- docs/versioning.md | 8 +++++--- 2 files changed, 9 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 59fae6f..fe15e21 100644 --- a/README.md +++ b/README.md @@ -103,15 +103,10 @@ Tagged commits trigger CI to publish: - npm (public): [`@o1-labs/mina-archive-node-graphql`](https://www.npmjs.com/package/@o1-labs/mina-archive-node-graphql) - Docker (GHCR): `ghcr.io/o1-labs/archive-node-api` -Normal releases after `1.0.0` are cut with: - -```sh -npm version -git push --follow-tags -``` - -For the initial `1.0.0` tag and current npm trusted-publishing caveat, see -the [versioning & schema stability policy](./docs/versioning.md#releasing). +A release PR bumps `package.json`, then a maintainer tags its merge commit. Do +not run `npm version` on `main`: `package.json` already carries the version +being released. Steps and the npm trusted-publishing caveat are in the +[versioning & schema stability policy](./docs/versioning.md#releasing). CI builds, publishes the npm package with provenance once npm trusted publishing is configured, and pushes Docker tags `1.2.3`, `1.2`, `1`, diff --git a/docs/versioning.md b/docs/versioning.md index cfc8110..ac02de1 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -130,12 +130,14 @@ Releases are cut in two steps: 1. A release PR bumps `package.json`/`package-lock.json` (and `src/schema-version.ts` if the schema moved) and merges to `main`. -2. A maintainer tags that merge commit; the tag push triggers the publish +2. A maintainer tags that merge commit from a checkout of it, so the tag and + the published version cannot disagree; the tag push triggers the publish pipeline: ```sh - git tag v$(node -p "require('./package.json').version") - git push origin v + git checkout + git tag v$(node -p "require('./package.json').version") + git push origin v$(node -p "require('./package.json').version") ``` Do not run `npm version` on `main`: `package.json` already carries the version