From 42aeeadd8e47523dc70a0f0bd88f602e2ac33015 Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Tue, 9 Jun 2026 15:01:26 +0000 Subject: [PATCH] Clarify AGENTS.md policy on compat shims for breaking changes The branching-model section banned @deprecated shims outright. The actual policy is that removal is the default and a shim is allowed as a deliberate design choice. Also make explicit that shimmed breaking changes still need a docs/migration.md entry, and echo that in the Breaking Changes section. --- AGENTS.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3d4c43dd7..1dbac17e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,10 +4,12 @@ -- `main` is currently the V2 rework. Breaking changes are expected here — when removing or - replacing an API, delete it outright and document the change in - `docs/migration.md`. Do not add `@deprecated` shims or backward-compat layers - on `main`. +- `main` is currently the V2 rework. +- Breaking changes are expected here — removing or replacing an API must be + intentional. Adding a replacement API or `@deprecated` shim must likewise be + a deliberate design choice, not bolted on for free. +- Breaking changes (including those softened by a backwards-compatibility + shim) must be documented in `docs/migration.md`. - `v1.x` is the release branch for the current stable line. Backport PRs target this branch and use a `[v1.x]` title prefix. - `README.md` is frozen at v1 (a pre-commit hook rejects edits). Edit @@ -117,7 +119,8 @@ What the existing pragmas mean: ## Breaking Changes -When making breaking changes, document them in `docs/migration.md`. Include: +When making breaking changes, document them in `docs/migration.md` — including +changes softened by a backwards-compatibility shim. Include: - What changed - Why it changed