[jeffdupont]

Stacked on #195 (the API reports).

Why

The API reports make every public change visible, but they don't stop a breaking change from shipping in a minor or patch release. After 1.0 a breaking change has to be deliberate: declared, and released as a major version.

What

scripts/api_breaking.py uses griffe to compare the names in each public module's __all__ with another git ref. The new API compatibility workflow runs it on every PR, and re-runs it when the title or labels change.

• On a PR (pr): compares with the PR's base. A breaking change fails unless one of these is true:
  • the PR title declares it with ! (feat!: ..., fix(client)!: ...), which makes release-please cut a major version (a minor one before 1.0.0);
  • an owner applied the api-compatible label because they judge the flagged change compatible.
• On the release PR (release): for each package whose version changes in .release-please-manifest.json, compares the code with that package's last release tag (<component>-<version>). It fails on a breaking change unless the new version is a major one (a minor one before 1.0.0), or an owner applied api-compatible to the release PR. A package with no release tag yet is reported and skipped.
• What counts as breaking:
  • from griffe: removed names, removed or moved parameters, new required parameters, changed defaults, changed attribute values;
  • added by the script: names dropped from __all__, and changed return types, which griffe doesn't flag.
• Experimental modules are skipped, because an experimental feature may change in a minor release.

Tested

• tests/test_api_breaking.py (23 tests) uses a throwaway git repo with a tagged release. It covers:

  • each breaking kind, and additive changes that pass;
  • experimental modules being skipped;
  • the title and label rules;
  • release versions before and after 1.0, including 0.9.0 → 1.0.0;
  • a package with no release tag;
  • api-compatible passing an undeclared breaking release, and another label not passing it.

  The fixture isolates git from the developer's global config.

• Full suite: uv run pytest gives 2579 passed, 14 skipped. ruff check and ruff format --check are clean, and actionlint passes on the workflow.

• Against real history:

  • pr against main: no breaking changes, so it passes.
  • pr against launchdarkly-ai-server-0.3.0: 23 breaking changes. That's 14 names that moved to experimental, plus capture_content's default changing from False to None in every provider factory, create_handler and ProviderHandler. It exits 1 with a plain title, and 0 with ! or the label.

The open release PR #166

Running release against #166 flags 6 provider packages:

• claude-agents, langchain-agents, openai-agents: 0.2.5 → 0.2.6
• claude-messages, langchain-messages, openai-messages: 0.2.4 → 0.2.5

Each changed capture_content's default from False to None (#158) since its last release, but is getting only a patch bump. client (0.3.0 → 0.4.0) passes.

If None means "use the default from configure()", callers see no difference. So the api-compatible label now also passes the release check (06050f1): an owner can judge a release PR compatible, the same way as any other PR. Verified on #166: it exits 1 without the label and 0 with it. The label now exists in this repo.

🤖 Generated with Claude Code

---

Note

Overview
Adds CI enforcement so undeclared public API breaks cannot ship in patch/minor releases.

A new API compatibility GitHub Actions workflow runs on every pull request (including title/label updates). For normal PRs it compares stable public modules (__all__, excluding .experimental.) against the base commit via griffe and fails when breaking changes are detected unless the title uses conventional ! (e.g. feat!:) or an owner applies the api-compatible label. On release-please release PRs it instead checks each bumped package against its last release tag and requires a major bump (or pre-1.0 minor bump) when the diff is breaking, with the same label escape hatch.

scripts/api_breaking.py implements that logic, including extra checks griffe misses (__all__ removals and return-type changes). scripts/api_report.py’s resolve() now takes a ModulesCollection so the breaking checker can reuse the same symbol resolution. tests/test_api_breaking.py covers detection rules, title/label behavior, semver alignment, and release edge cases in an isolated git fixture.

^{Reviewed by Cursor Bugbot for commit 06050f1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 06050f1. Configure here.}

[cursor]

Removed modules evade the check

Medium Severity

check_pr and check_release only compare modules discovered in the current tree, so a deleted public package never enters the comparison set. The the module was removed path in compare never runs, and dropping a published module is treated as compatible.

Additional Locations (2)

• scripts/api_breaking.py#L87-L92
• scripts/api_breaking.py#L192-L200

 

^{Reviewed by Cursor Bugbot for commit 06050f1. Configure here.}