kb/openspec/changes/independent-versioning/proposal.md at 528a09ca909af0b6155c3a85eecaa97208d20eb3

steve/kb

Files

T

steve 528a09ca90 Independent client/engine versioning with compatibility check

Split release.sh into release-client.sh and release-engine.sh for
independent release cadences. Client checks engine version on first
API call and hard-fails if engine is below MinEngineVersion.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-28 15:59:16 +00:00

2.4 KiB

Raw Blame History

Why

Client and engine are currently locked to the same version number and released together via a single script. This means a client-only bug fix (e.g. output formatting) forces a full engine Docker image rebuild and push, and vice versa. Decoupling versions allows each component to be released independently on its own cadence, while a compatibility check ensures users don't run a client that requires engine features not yet deployed.

What Changes

Separate version files — client/VERSION and engine/VERSION may diverge (they already exist as separate files, but are currently always set to the same value)
Split release script — Replace single release.sh with release-client.sh (builds Go binaries, tags client-vX.Y.Z, creates release) and release-engine.sh (builds Docker images, tags engine-vX.Y.Z, creates release, pushes images)
Client compatibility check — Client embeds a MinEngineVersion constant (set at build time or in code). On every command that contacts the engine, the client calls GET /api/v1/status, compares the engine's reported version against MinEngineVersion, and hard-fails with an actionable error if the engine is too old. No skip flag, no warning — just a clear error with upgrade instructions.
Tag naming convention — client-vX.Y.Z and engine-vX.Y.Z replace the current vX.Y.Z tag format. BREAKING — existing tag format changes.

Capabilities

New Capabilities

(none)

Modified Capabilities

go-client: Add engine version compatibility check requirement (hard fail if engine version < MinEngineVersion)
engine-api: Status endpoint already returns version — no change needed, but delta spec documents the contract that the version field is required for compatibility checking
docker-deployment: Compose files pin engine image tag; release script changes affect image tagging

Impact

release.sh — replaced by release-client.sh + release-engine.sh
client/cmd/root.go — new MinEngineVersion constant
client/internal/api/client.go — version check on first API call
client/Makefile — may inject MinEngineVersion via ldflags alongside Version
Git tags — new naming convention (client-v*, engine-v*)
Gitea releases — two separate releases per independent release cycle
engine/compose.nvidia.yaml, engine/compose.rocm.yaml — add pinned image tag

2.4 KiB Raw Blame History

Why