up

docs/api/versioning.md

@@ -0,0 +1,41 @@
+# API Versioning
+
+Last updated: 2025-11-25 (Docs Tasks Md.V)
+
+## Principles
+- **Semantic versioning**: OpenAPI artifacts follow `MAJOR.MINOR.PATCH` where breaking changes bump MAJOR, additive changes bump MINOR, fixes/docs bump PATCH.
+- **Long-lived compatibility**: At least N-1 major versions remain runnable for 12 months; minor versions remain compatible for 6 months after release unless a security fix requires earlier removal.
+- **Explicit deprecations**: Every breaking removal/change is preceded by a deprecation window with headers and changelog entries.
+- **Deterministic specs**: Generated `out/api/*.yaml` are reproducible from a pinned manifest and committed checksums.
+
+## How versions are expressed
+- **Base URL**: `/api/v{major}/...` (e.g., `/api/v1/policy`). Major only; minor/patch controlled via headers.
+- **Headers**:
+  - `X-Stella-Api-Version: <major.minor.patch>` → client-requested minor/patch; server chooses the highest compatible available ≤ requested. If omitted, server serves the latest compatible minor/patch for that major.
+  - `Deprecation: true` + `Sunset: <rfc7231-date>` returned when an endpoint or field is scheduled for removal.
+  - `X-Stella-Api-Deprecated-Fields: field1,field2` lists soon-to-be-removed members for the response.
+- **Error codes**:
+  - `error.code = API_VERSION_UNSUPPORTED` when requested major is not served.
+  - `error.code = API_VERSION_TOO_OLD` when requested minor/patch is below the minimum supported for the major.
+
+## Compatibility rules
+- Additive changes (new fields/enums/paths) are allowed within the same major; fields default to `null`/empty and must not change meaning.
+- Breaking changes require a new major: field removals/renames, required field additions, behavior changes that alter contracts.
+- Enum extensions: existing values remain; new values must be tolerated by clients.
+- Pagination/order: sort keys and determinism must be preserved across versions.
+
+## Release & lifecycle
+1) Draft OpenAPI in `src/Api/StellaOps.Api.OpenApi` and update `out/api/stella.yaml`.
+2) Run `pnpm api:lint` + `pnpm api:compat --baseline stella-baseline.yaml` to ensure no unintended breaks.
+3) Publish changelog entry under `out/api/changelog/<yyyyMMdd>-<version>.md` with checksums/signature.
+4) Announce deprecations via release notes; include `Deprecation`/`Sunset` headers in affected endpoints for at least 60 days before removal.
+5) Sunset execution: remove endpoints/fields only after the sunset date and after the major bump ships.
+
+## Client guidance
+- Always send `X-Stella-Api-Version` to lock to a tested minor/patch; pin SDK versions accordingly.
+- Handle `Deprecation`/`Sunset` headers by warning users and planning upgrades.
+- Prefer server-provided pagination tokens; avoid relying on incidental field order.
+
+## Testing
+- Contract tests must cover the lowest and highest supported minor/patch for each major.
+- Deterministic fixtures for each version live under `tests/fixtures/api/versioning/`; CI runs `pnpm api:compat` against these fixtures.