Handling breaking changes: automating semantic versioning for API SDKs (August 2026)

Generated API SDKs should derive semantic version bumps from changes to their API contracts or generated public surfaces rather than commit messages, because package managers automatically treat version ranges as compatibility guarantees. API and SDK compatibility can differ: additions such as enum values or optional response fields may be nonbreaking over HTTP but break typed clients, while generator configuration, runtime requirement, or exported-name changes can break an SDK without altering the wire API. The text recommends combining specification-level diffs, such as oasdiff, with generated-surface diffs to identify changes, calculate major, minor, or patch releases against the last published version, and require human approval for major releases. It also highlights multi-language complications including Go’s semantic import paths and immutable registries, suggesting policies such as lockstep major versions with independent lower versions. Safe major-version releases should include machine-readable deprecation and sunset notices, maintenance support for prior majors, migration documentation and tooling, and changelogs generated from the same classified diff. Fern is presented as a platform that automates diff-based version calculation, CI gating, SDK generation, testing, changelog creation, and publishing across nine languages.

Use this post, company, and trend context to find content marketing opportunities, perform competitive analysis, or address product feature gaps via the Plushcap MCP server or the Plushcap API.