Migration Guide in Changelogs

From Breaking Changes to Migration Guides

A well-written changelog does more than list breaking changes — it helps users understand what to do about them. While the generator creates the structural foundation (a dedicated BREAKING CHANGES section), the quality of the migration guidance depends on the commit messages themselves.

Writing Migration-Friendly Commits

Compare these two commit messages:

Poor:

feat(api)!: update user endpoint

Better:

feat(api)!: change /users response from object to paginated array

The second message tells the reader exactly what changed. When this appears in the changelog, it provides enough context for the reader to understand the migration requirement.

Structuring a Migration Changelog

For major version releases, consider organizing your input commits to produce a changelog that reads like a migration guide:

## [3.0.0] - 2026-02-27

### BREAKING CHANGES
- **api:** change /users response from object to paginated array
- **auth:** require API key header on all endpoints
- **config:** rename DATABASE_URL to DB_CONNECTION_STRING

### Added
- **api:** add cursor-based pagination to all list endpoints
- **auth:** add API key management dashboard

### Fixed
- **api:** resolve N+1 query on /users endpoint

Complementing with External Docs

For complex migrations, the changelog entry should link to a detailed migration guide. Include a note at the top of the breaking changes section:

### BREAKING CHANGES
> See the [Migration Guide](./MIGRATION-3.0.md) for detailed upgrade instructions.

Version Bump Checklist

When your changelog includes breaking changes, verify:

1. The version follows Semantic Versioning (major bump)
2. Each breaking change is descriptive enough to guide action
3. The generated output is reviewed before publishing