docs(governance): define the 0.x breaking-change notice procedure#43
Open
ucekmez wants to merge 1 commit into
Open
docs(governance): define the 0.x breaking-change notice procedure#43ucekmez wants to merge 1 commit into
ucekmez wants to merge 1 commit into
Conversation
The versioning policy permits breaking changes between 0.x minors with a "30-day notice" but never said where the notice is posted or how a consumer detects a pending break. Add a concrete procedure: a CHANGELOG "Breaking changes (pending)" entry, a pinned GitHub Discussions announcement, and the EEP-Version negotiation path (+ optional Deprecation/Sunset headers), with the 30-day clock starting at merge. Surfaced by the EEP protocol audit (finding GOV-2). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Ugur Cekmez <ucekmez@gmail.com>
There was a problem hiding this comment.
Pull request overview
Adds a documented, multi-channel procedure for announcing breaking changes during the 0.x semver phase, clarifying how the “30-day notice” requirement is communicated and when the countdown begins.
Changes:
- Introduces a “0.x breaking-change procedure” subsection under the versioning policy in
GOVERNANCE.md. - Specifies the notice must be delivered via CHANGELOG, pinned GitHub Discussions, and the EEP-Version negotiation path (with optional
Deprecation/Sunsetheaders). - Defines when the 30-day clock starts (at merge behind a pending-version mechanism) and states it’s an interim policy until
v1.0.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+61
to
+63
| - the `EEP-Version` negotiation path ([SPECIFICATION.md §3.1.1](./docs/current/SPECIFICATION.md)): servers SHOULD advertise the upcoming version once the notice opens, and MAY emit a `Deprecation` / `Sunset` response header on affected endpoints. | ||
|
|
||
| The 30-day clock starts when the change merges to `main` behind its pending-version flag. This interim procedure applies until the formal 18-month deprecation policy takes effect at `v1.0`. |
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
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.
Problem
The versioning policy permits breaking changes between
0.xminor versions with a "30-day notice", but defines no channel or mechanism for that notice — nothing says where it is posted, how a consumer detects a pending break, or when the clock starts.Fix
Add a "0.x breaking-change procedure" subsection requiring the 30-day notice to be delivered through all of:
### Breaking changes (pending)entry inCHANGELOG.md(Unreleased), naming the change + target version;EEP-Versionnegotiation path (§3.1.1), with optionalDeprecation/Sunsetheaders on affected endpoints.The clock starts at merge behind the pending-version flag; this interim procedure applies until the formal 18-month deprecation policy at
v1.0.Docs-only. Surfaced by the EEP protocol audit (finding GOV-2). Touches a
GOVERNANCE.mdregion disjoint from #42's (the EEIP table), so the two merge cleanly.🤖 Generated with Claude Code