Semantic versioning and changelogs
Explain compatibility decisions instead of relying on a version number alone.
01Define the public compatibility contract
List the API, configuration and supported runtimes covered by your versioning policy. Under Semantic Versioning, a stable major release signals incompatible public API changes, a minor adds backward-compatible functionality, and a patch fixes backward-compatible bugs.
02Handle prereleases and zero-major versions deliberately
A prerelease is not the same stability promise as its eventual stable release. SemVer treats 0.y.z as initial development; document your own compatibility policy so consumers do not assume every 0.x minor is safe.
03Explain why the version changed
A major number warns of risk but cannot tell a maintainer which call sites to edit. Group additions, fixes, breaking changes and deprecations with concrete migration instructions. A deprecation can precede the eventual incompatible removal.
04Keep ranges and published history consistent
Never rewrite a released version to mean different code. Publish a new version and explain the correction. Test version diffs against actual tags and package artifacts; structured release entries help agents retrieve the intervening changes but cannot compensate for inaccurate version labels.
Before and after
Too vague
2.0.0: general improvements.
Specific and actionable
2.0.0 removes synchronous connect(). Replace it with await connectAsync() and handle rejected connection attempts. The major increment reflects this public API incompatibility; unrelated fixes are listed separately.
Fictional example — use your own verified names, versions and behavior.
Before you publish
- Document the public API boundary
- State the 0.x and prerelease policy
- Explain each incompatible change
- Match tags and registry versions
- Do not rewrite released artifacts
Common questions
Keep reading
LogPulse
Changelogs coding agents can upgrade from.
Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.