How to document breaking changes
Turn an incompatibility into a bounded, reviewable migration.
01Define exactly who is affected
Name the removed API, changed default or unsupported runtime. Include affected versions and conditions. A breaking change that only applies to custom serializers should not sound like every consumer must rewrite their application.
02Show the before and after
Provide a minimal failing usage and its replacement. Explain semantic changes as well as syntax: a renamed timeout key is different from changing its unit from seconds to milliseconds.
03Order the work and state reversibility
Give prerequisites, dependency updates, data migrations and deployment order. For database changes, describe backup and compatibility requirements. Say when a rollback stops being safe instead of promising an undo button.
04Add a verification target
Document a focused test that proves the new behavior, then ask maintainers to run their full suite. In LogPulse, publish the summary, affected surface and migration in structured breaking-change fields so version-diff consumers receive actionable facts.
Before and after
Too vague
Removed legacy auth.
Specific and actionable
2.0.0 removes config.apiKey. Set config.token to a scoped access token before upgrading. Verify GET /account succeeds with the required read scope. Existing API keys cannot be used as tokens.
Fictional example — use your own verified names, versions and behavior.
Before you publish
- Name the affected surface
- Show before and after usage
- Document deployment order
- State rollback limits
- Provide a success check
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.