From 54bcc1ca3761c40cb36f06f1ca3f3b1448c1f0ed Mon Sep 17 00:00:00 2001 From: Ugur Cekmez Date: Mon, 1 Jun 2026 21:16:46 +0300 Subject: [PATCH] docs(governance): define the 0.x breaking-change notice procedure 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) Signed-off-by: Ugur Cekmez --- GOVERNANCE.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index c0bcbaa..ee9d545 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -52,6 +52,16 @@ EEP follows [Semantic Versioning](https://semver.org/) (semver): - `1.x` — Stable. No breaking changes in patch releases. Minor versions add features but must remain additive. Breaking changes require a new major version. - Platforms must advertise their supported EEP version in all responses via the `EEP-Version` header. +### 0.x breaking-change procedure + +Because `0.x` permits breaking changes between minor versions, each such change MUST be announced with a **30-day notice** delivered through *all* of: + +- a `### Breaking changes (pending)` entry in [`CHANGELOG.md`](./CHANGELOG.md) under **Unreleased**, naming the change and its target version; +- a pinned **GitHub Discussions** post in the *Announcements* category; +- 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`. + ## License The EEP specification uses the Apache 2.0 license. Implementations are free to be open or proprietary.