From e5b1d038bff126519c3895e532860eb48dd943b3 Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Tue, 11 Aug 2026 15:10:41 +0000 Subject: [PATCH] Close the door on breaking changes in AGENTS.md The Branching Model bullets and the "Breaking Changes" section were written while v2 was still being assembled, and read as a workflow for making breaking changes: be intentional, then document it in docs/migration.md. Now that 2.x is the released stable line, the guidance an agent should find is "don't, and escalate if you think you must". Replace the two bullets with the 2.x compatibility contract and mark docs/migration.md as closed to new entries, and replace the Breaking Changes section with an API Stability section that says the same thing at the point an agent goes looking for permission. No-Verification-Needed: contributor-guidance doc only --- AGENTS.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2812ed6d17..0acfecfb4b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,11 +4,16 @@ - `main` is the current stable line (v2); releases are cut from it (see `RELEASE.md`). -- Removing or replacing an API must be intentional, and what shipped in 2.x - is public surface. Adding a replacement API or `@deprecated` shim is - likewise a deliberate design choice, not bolted on for free. -- Changes that break code written against v1 (including those softened by a - backwards-compatibility shim) must be documented in `docs/migration.md`. +- v2 is released; its public API is a compatibility contract for the whole + 2.x line. Don't remove, rename, or change the signature or observable + behaviour of anything public (the `mcp` `__all__` surface, `mcp-types`, + documented behaviour). If a task seems to require that, stop and tell the + user — it isn't a decision to make inside a PR. See API Stability below. +- Additions are permanent: whatever public surface ships in a 2.x release + joins the same contract. New public symbols and `@deprecated` shims are + deliberate design choices, never a convenience. +- `docs/migration.md` is the v1 → v2 record and is closed to new entries. + Correcting errors or improving clarity in what's there is fine. - `v1.x` is the maintenance branch for the previous major. Backport PRs target it and use a `[v1.x]` title prefix; only critical bug fixes and security fixes land there. @@ -123,17 +128,22 @@ What the existing pragmas mean: - `# pragma: no branch` — excludes branch arcs only. coverage.py misreports the `->exit` arc for nested `async with` on Python 3.11+ (worse on 3.14/Windows). -## Breaking Changes +## API Stability -When making breaking changes, document them in `docs/migration.md` — including -changes softened by a backwards-compatibility shim. Include: +The 2.x line has no breaking changes. Anything that would make code written +against a released 2.x version stop working — a removed or renamed symbol, a +changed signature, changed observable behaviour — is out of scope, including +versions softened by a compatibility shim or deprecation warning. If you +conclude a task can't be done without one, stop and surface that to the user +instead of implementing it. -- What changed -- Why it changed -- How to migrate existing code +`docs/migration.md` documents the v1 → v2 migration and is complete. Don't add +sections to it; there is nothing new to migrate. Fixing errors or clarifying +existing sections is welcome. -Search for related sections in the migration guide and group related changes together -rather than adding new standalone sections. +A fix that brings behaviour in line with what its docstring or the spec +already says is not a breaking change, but call out the behaviour delta in the +PR description so a reviewer can weigh who might depend on the old behaviour. ## Documentation