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
parent b04823e67b
commit 528a09ca90
14 changed files with 729 additions and 93 deletions
@@ -0,0 +1,32 @@
+## 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