Breaking changes

A breaking change is anything that can stop your code from compiling or running correctly after an update. We surface two kinds:

• Documented. The maintainer flagged it in the release notes (e.g. "BREAKING:", a major version bump per semver, an entry under "Breaking changes").
• Undocumented. The diff shows a change that fits the pattern of a breaking change, but the release notes don't mention it. See Undocumented changes for the detection details.

What counts as breaking #

The model is prompted to flag, at minimum:

• Function signature changes (parameter added/removed/reordered, type changed).
• Removed or renamed exports (a symbol you might be importing is gone).
• Class hierarchy changes (a base class removed, an interface tightened).
• Changes to default values for parameters.
• Changes to return types or thrown exceptions.

Outside of pure-code changes, we also flag:

• Removed CLI flags or environment-variable changes.
• Configuration-schema changes that aren't backward-compatible.
• Wire-format changes for serialized data.

Our false-positive policy #

We bias toward flagging — if there's ambiguity about whether a change is breaking, we err on the side of telling you. The reasoning: a missed breaking change costs you a debugging session in production; a false positive costs you 30 seconds reading the summary.

When the analysis is uncertain (e.g. "this looks like a signature change but the function is in a _internal namespace"), the summary will say so explicitly rather than asserting the change as definitely breaking.

What to do with a flagged change #

1. Read the summary — it cites the specific lines and files.
2. Click through to the diff — verify the change matches the description.
3. Search your own codebase for usage of the affected API (your editor's "find references" will do).
4. Decide whether to update, pin, or wait for a follow-up patch.