---
title: "Check every release against the public API · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/libraries-and-sdks/semver-check
id: ENG-51
level: Recommended
updated: 2026-10-22
tokens: 853
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Check every release against the public API

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Libraries and SDKs](https://agentwranglers.se/playbook/engineering/libraries-and-sdks.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: ENG-51
- Level: Recommended
- Chapter: [Libraries and SDKs](https://agentwranglers.se/playbook/engineering/libraries-and-sdks.md)
- Rule: In CI, compare the public API of each change with the last published release. Fail when a breaking change comes without a major version bump.
- Check: A test change that removes a public function, with only a minor version bump, makes the CI job fail. A change that only adds a function passes.
- How: A person cannot spot every breaking change by eye, such as a new required parameter or a narrowed return type. A tool can, by diffing the API surface. Examples are API Extractor for TypeScript, griffe for Python, cargo-semver-checks for Rust, japicmp for Java, and gorelease for Go. Removals and signature changes need a major version, and additions a minor one. Publish from CI as [Publish your packages without stored tokens](https://agentwranglers.se/playbook/adversarial-testing/supply-chain-and-setup/trusted-publishing.md) says. List every change in the changelog, as [Keep a changelog](https://agentwranglers.se/playbook/api-design/changes-over-time/api-changelog.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### YAML example

```yaml
# Python package: compare with the last tag
- run: griffe check invoices --against "$(git describe --tags --abbrev=0)"
# Rust crate: compare with the last version on crates.io
- run: cargo semver-checks
```

## Sources

- [Semantic Versioning 2.0.0](https://semver.org/)

## Related rules

- ENG-50 [Declare the public API and hide the rest](https://agentwranglers.se/playbook/engineering/libraries-and-sdks/declare-public-api.md) in Engineering
- SEC-77 [Publish your packages without stored tokens](https://agentwranglers.se/playbook/adversarial-testing/supply-chain-and-setup/trusted-publishing.md) in Adversarial testing
- API-31 [Keep a changelog](https://agentwranglers.se/playbook/api-design/changes-over-time/api-changelog.md) in API design
- OSS-18 [Build every release in CI with signed provenance](https://agentwranglers.se/playbook/open-source/releases/release-provenance.md) in Open source maintenance

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/engineering/libraries-and-sdks/semver-check">Agent Wranglers engineering playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Declare the public API and hide the rest](https://agentwranglers.se/playbook/engineering/libraries-and-sdks/declare-public-api.md)
- Next: [Deprecate in a minor release before removing in a major one](https://agentwranglers.se/playbook/engineering/libraries-and-sdks/deprecation-policy.md)
- [Libraries and SDKs](https://agentwranglers.se/playbook/engineering/libraries-and-sdks.md)