From 7deef8c210b8d181357ad9e21add2bd3e31f5116 Mon Sep 17 00:00:00 2001 From: Jace Date: Sat, 1 Aug 2026 22:01:46 -0700 Subject: [PATCH] docs: make v1.5.0 the /v1 GA compatibility baseline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The doc set its own trigger — "the first official API GA tag supersedes the commit anchor, and every later release must compare against the most recent GA tag" — and v1.5.0 (2026-08-02) is that tag. Release audits now compare against v1.5.0 rather than the pre-release freeze anchor af5d3c74. Verified the documented command runs clean: make openapi-compat-check OPENAPI_BASE=v1.5.0:api/openapi.yaml → No changes detected The old anchor is kept, marked superseded, because audits reaching back into pre-GA history still need it and its rationale (it deliberately sits after the pre-GA bounds program) is not reconstructible from the commit alone. Note this baseline is a manual release-audit instruction, not automation: CI compares against the pull-request base and the push-before SHA, and never referenced the anchor. Co-Authored-By: Claude Opus 5 --- docs/api-compatibility-gate.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/api-compatibility-gate.md b/docs/api-compatibility-gate.md index e5592fa1e..f3186d6fa 100644 --- a/docs/api-compatibility-gate.md +++ b/docs/api-compatibility-gate.md @@ -23,23 +23,23 @@ event- or error-specific schema lookup. ## Freeze baseline -The cumulative pre-release `/v1` freeze anchor is commit -`af5d3c7486db76cf7e62ba18763b47e4a5b95b35`, the mainline contract immediately -before the strict GA policy was enabled. This intentionally comes after the -pre-GA bounds program; an earlier gate-introduction commit would make those -approved pre-freeze request bounds look retroactively breaking. Until the first -explicitly announced API GA release tag exists, release audits compare the -candidate against this anchor as well as the normal pull-request base: +**`/v1` went generally available with `v1.5.0` (2026-08-02).** That tag is the +compatibility baseline: release audits compare the candidate against the most +recent GA tag, in addition to the normal pull-request base. ```sh -make openapi-compat-check \ - OPENAPI_BASE=af5d3c7486db76cf7e62ba18763b47e4a5b95b35:api/openapi.yaml +make openapi-compat-check OPENAPI_BASE=v1.5.0:api/openapi.yaml ``` Existing `v1.0.x` tags are application/cherry-pick releases that predate the -API contract freeze; they are not `/v1` compatibility baselines. The first -official API GA tag supersedes the commit anchor, and every later release must -compare against the most recent GA tag. +API contract freeze; they are not `/v1` compatibility baselines. + +Superseded — kept because audits of pre-GA history still need it: before a GA +tag existed, the anchor was commit `af5d3c7486db76cf7e62ba18763b47e4a5b95b35`, +the mainline contract immediately before the strict GA policy was enabled. It +deliberately sits after the pre-GA bounds program, because an earlier +gate-introduction commit would make those approved pre-freeze request bounds +look retroactively breaking. ## Policy