Skip to content

Commit eb43bb6

Browse files
committed
Stop framing breaking changes as a workflow in AGENTS.md
The Branching Model bullets and the "Breaking Changes" section were written while v2 was still being assembled, and read as instructions for making a breaking change: be intentional about it, then write it up in docs/migration.md. With 2.x released that nudges the wrong way. State the 2.x compatibility contract in one bullet, mark docs/migration.md as closed to new entries, and drop the Breaking Changes section, which only existed to describe how to add to that file. No-Verification-Needed: contributor-guidance doc only
1 parent 5285e93 commit eb43bb6

1 file changed

Lines changed: 7 additions & 17 deletions

File tree

AGENTS.md

Lines changed: 7 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,13 @@
44

55
- `main` is the current stable line (v2); releases are cut from it (see
66
`RELEASE.md`).
7-
- Removing or replacing an API must be intentional, and what shipped in 2.x
8-
is public surface. Adding a replacement API or `@deprecated` shim is
9-
likewise a deliberate design choice, not bolted on for free.
10-
- Changes that break code written against v1 (including those softened by a
11-
backwards-compatibility shim) must be documented in `docs/migration.md`.
7+
- v2 is released; its public API is a compatibility contract for the 2.x
8+
line. Removals, renames, or any change to an existing API's signature or
9+
observable behaviour (including ones softened by a `@deprecated` shim) is a
10+
design decision a maintainer makes explicitly, and should generally be
11+
avoided.
12+
- `docs/migration.md` is the v1 → v2 record and is closed to new entries.
13+
Correcting errors or improving clarity in what's there is fine.
1214
- `v1.x` is the maintenance branch for the previous major. Backport PRs
1315
target it and use a `[v1.x]` title prefix; only critical bug fixes and
1416
security fixes land there.
@@ -128,18 +130,6 @@ What the existing pragmas mean:
128130
- `# pragma: no branch` — excludes branch arcs only. coverage.py misreports the
129131
`->exit` arc for nested `async with` on Python 3.11+ (worse on 3.14/Windows).
130132

131-
## Breaking Changes
132-
133-
When making breaking changes, document them in `docs/migration.md` — including
134-
changes softened by a backwards-compatibility shim. Include:
135-
136-
- What changed
137-
- Why it changed
138-
- How to migrate existing code
139-
140-
Search for related sections in the migration guide and group related changes together
141-
rather than adding new standalone sections.
142-
143133
## Documentation
144134

145135
When a change affects public API or user-visible behaviour, update the relevant

0 commit comments

Comments
 (0)