docs: make v1.5.0 the /v1 GA compatibility baseline - #797
Merged
Conversation
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 af5d3c7. 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 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
/v1went GA with v1.5.0 on 2026-08-02, which fires a trigger the doc set for itself:So release audits should now compare against
v1.5.0, not the pre-release freeze anchoraf5d3c74.What changed
The baseline command becomes:
Verified it actually runs — a doc that prescribes a command should prescribe one that works:
(Correct: v1.5.0 was cut from
mainand nothing has touched the spec since.)What was kept, and why
The old anchor stays, explicitly marked superseded. Two reasons: audits reaching back into pre-GA history still need it, and its rationale isn't reconstructible from the commit alone — it deliberately sits after the pre-GA bounds program, because an earlier gate-introduction commit would make those approved pre-freeze bounds look retroactively breaking. Deleting it would lose that.
Scope note
This baseline is a manual release-audit instruction, not automation. CI compares against
github.event.pull_request.base.shaandgithub.event.before; the anchor was never referenced by any workflow or the Makefile (git grep af5d3c74matches this doc only). So this changes what a human runs during a release audit, and nothing in the automated gate.🤖 Generated with Claude Code