build(api): guard that api.json changes require an info.version bump

[joewiz]

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

Summary

The OpenAPI contract version (modules/api.json → info.version) should be versioned independently of the package version (pom.xml): the API contract changes rarely, while the package changes on most fixes — so tying them in lockstep would churn the contract version on every Java/internal change. (Thanks @line-o, @duncdrum — this supersedes the lockstep-templating approach this PR originally opened with.)

This PR:

1. Pins info.version to a fixed 0.9.0 baseline — it was a stale 0.9.0-SNAPSHOT, and it no longer derives from ${project.version}. (Baseline value is a team call; easy to change.)
2. Adds a CI guard — .github/workflows/api-version-guard.yml — that fails a PR if modules/api.json changed without info.version changing (@duncdrum's suggestion). That keeps the contract version honest while fully decoupling it from the package.

What it deliberately does not do

The guard enforces that the version bumped, not the size (patch/minor/major) — that's the author's semver judgment for now. Automating an independent API semver track (so the bump size is derived rather than hand-picked) is a follow-up: #62.

Note on the baseline

info.version had drifted — stale at 0.9.0-SNAPSHOT across several releases. 0.9.0 is a clean starting point for the now-independent track; pick a different baseline if the team prefers.

[line-o]

I would not want to tie the API version directly to the version of the package.

• My main argument against it: not every fix or change in this package will change the API. In fact I expect to see the API stabilize quickly and then change seldomly and certainly not in lockstep with the package.

• I do see the value of not having to think about API versioning on top of package versioning. So there is a potential drift.

If we were to publish exist-db 8 and a package of existdb-openapi that requires exist-db 8 but the API is stil compatible - how would we do that with this setup?

Let's discuss this today in the community meeting. I added it to the agenda.

[duncdrum]

As long as we are below 1.0.0 I see little reason not to stay in sync given the special sem ver provisions for 0.x.x.

How would you decide when to bump the version automatically @line-o ?

[line-o]

API Version is a contract that changes only if api.json itself changes

[duncdrum]

So add a CI check for changes to api.json that turns red if file is changed but version isn't ? Or something more elaborate ?

[line-o]

That would be much better than to raise the version in lockstep with the package.

[joewiz]

Ah, I see the issue... I will look into whether conventional commit scopes gives us the semantics needed to assert that a particular version property in a file like our api.json within the repo needs to be bumped, as opposed to the package as a whole.

[joewiz]

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

@line-o you're right — tying the API version to the package version is wrong: the contract changes far less often than the package, and a Java/internal fix shouldn't churn the contract version. I've dropped the lockstep templating.

Reworked to @duncdrum's suggestion instead: a CI guard that fails a PR if modules/api.json changes without an info.version bump (.github/workflows/api-version-guard.yml), and pinned info.version to a 0.9.0 baseline (it had been stale at 0.9.0-SNAPSHOT). That keeps the contract version honest and fully decoupled from the package.

The guard enforces that the version bumps, not the size — automating an independent API semver track (deriving the bump) is a follow-up: #66. Re-review welcome.