docs: add API_STABILITY.md commitment + deprecation policy (#474)#593
Merged
Conversation
Specifies what currently has no public contract: - Alpha caveat: 0.x line makes no compatibility guarantees; pinning exact versions is the only insulator during alpha. - Post-v1 semver policy (patch / minor / major) and what each bump is allowed to change. - Three stability tiers (stable, beta, experimental) declared in OpenAPI via x-stability. Beta + experimental require the Accept-Stability request header so SDK clients don't reach them by accident. - RFC 8594 deprecation policy: ≥ 2 minor releases of lead time + ≥ 90 days for SDK-affecting deprecations, with synchronized signals on response headers, CHANGELOG, DEPRECATIONS.md, and GitHub release notes. - Breaking-change PR checklist. Adopting these tiers in OpenAPI + SDK is a follow-up; this doc is the contract those follow-ups conform to.
README "Documentation" list adds a row for the new doc. CONVENTIONS.md §7 (Deprecation) gets a one-line lede pointing at API_STABILITY.md for the stability commitment + lead-time policy — keeps CONVENTIONS focused on header shape and avoids duplicating the same policy in two places. Closes #474.
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.
Closes #474.
What
Publishes
docs/API_STABILITY.md— the missing public commitment that the README's "alpha" badge currently lacks. Covers:0.x(no compatibility guarantees; pin exact versions).stable,beta,experimental) declared via OpenAPIx-stability. Beta + experimental require anAccept-Stabilityheader so SDK clients don't reach them by accident.DEPRECATIONS.md, and GitHub release notes.README.md"Documentation" list gets a row for the new doc.CONVENTIONS.md §7 Deprecationgains a one-line lede pointing here so the policy doesn't get duplicated in two places.Notes
Wiring the
x-stabilityextension into the OpenAPI spec + SDK is a separate follow-up (issues to be filed after this lands). This PR is the contract those follow-ups conform to.Test plan
#deprecation,DEPRECATIONS.mdplaceholder ok — covered by [Docs] Create docs/ERRORS.md and docs/DEPRECATIONS.md required by CONVENTIONS.md #576)