Automate an independent API-contract version track (decoupled from the package version)

[joewiz]

[This issue was co-authored with Claude Code. -Joe]

Background

modules/api.json's info.version is the API contract version, tracked independently of the package version (pom.xml) — the contract changes far less often than the package. #63 established the floor: a CI guard that fails a PR if api.json changes without an info.version bump. But the bump itself is currently manual — the author picks the new version and its size (patch/minor/major) by hand.

This issue: automate the API-version bump on its own track, alongside whatever package-release automation we adopt (conventional commits / semantic-release).

Prior art — independent versioning of a sub-artifact

This is well-trodden ground; a few approaches other projects use, for consideration:

• Route a commit's version impact by scope or path (monorepo release tooling). semantic-release-monorepo versions each component from the commits that touch its files; GitVersion 6 computes per-project versions from per-project history. We could run a second release lane that considers only API-affecting commits (by path — modules/api.json — and/or by a dedicated commit scope) and bumps/tags the API version separately from the package. (npm tooling comparison, GitVersion monorepo)
• info.version is designed to move at its own rate — distinct from the implementation/package version. (OpenAPI info.version)
• Derive the bump from the actual spec diff. The Phoenix project tracks info.version from a dedicated file and runs oasdiff to classify accumulated changes between releases (breaking → major, additive → minor, else patch) and bump automatically — no reliance on commit-message discipline. (oasdiff · Arize-ai/phoenix#12111)

Rough options

1. Scope/path-routed second release lane — analyze only API-affecting commits to compute the API bump; package release stays separate. Lightweight; relies on commit discipline, which the build(api): guard that api.json changes require an info.version bump #63 guard backstops.
2. Spec-diff-driven (oasdiff) — compute the bump from the api.json diff between releases; no commit-annotation discipline needed. More robust, heavier to wire.
3. A hybrid (e.g. spec-diff to propose, commit metadata to confirm).

Decision on approach + tooling can wait until package auto-release lands; the #63 guard is the interim floor.

[joewiz]

[This response was co-authored with Claude Code. -Joe]

Closing as a duplicate of #62, which @line-o opened to discuss API versioning more broadly — that's the right home for this. The prior-art notes above stay visible for reference; let's continue in #62.

[line-o]

@joewiz I would rather keep this open as well - as it is part of the effort to have the API properly versioned.