Skip to content

Clarify AGENTS.md policy on compat shims for breaking changes #2823

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maxisbey merged 1 commit into from
Jun 9, 2026
+8 −5
Merged

Clarify AGENTS.md policy on compat shims for breaking changes #2823

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,12 @@

<!-- TODO: drop this section once v2 ships and main becomes the stable line -->

- `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
Expand Down Expand Up @@ -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
Expand Down
Loading