Breaking Change with Detailed Migration Guide

Writing Comprehensive Breaking Change Messages

When a breaking change is significant, the commit message body should serve as a mini migration guide. This is especially important for libraries and APIs with external consumers who will see the commit in changelogs.

Full Example

feat(config)!: replace JSON config with YAML format

Migrate the application configuration from config.json
to config.yaml. The YAML format supports comments,
multi-line strings, and anchors, which were frequently
requested by users.

Before:
  {
    "port": 3000,
    "database": {
      "host": "localhost",
      "port": 5432
    }
  }

After:
  port: 3000
  database:
    host: localhost
    port: 5432

BREAKING CHANGE: config.json is no longer read. Rename
your configuration file to config.yaml and convert the
syntax from JSON to YAML. A migration script is available
at scripts/migrate-config.js.

Structure for Migration Bodies

A well-structured breaking change body includes:

1. What changed — one or two sentences explaining the modification
2. Why it changed — the motivation (performance, user requests, simplification)
3. Before/After examples — concrete code or configuration snippets
4. Migration steps — numbered list of what users need to do
5. Migration tooling — mention any scripts, codemods, or documentation

Line Wrapping in the Body

Keep body lines at 72 characters or fewer. This ensures readability in:

• git log (which adds 4-space indent)
• GitHub's commit detail view
• Changelog generators that render commits as-is

Multiple Breaking Changes

If a single commit introduces multiple breaking changes, list each in the footer:

feat!: overhaul API response format

BREAKING CHANGE: Response envelope changed from
{ data, error } to { result, errors }.

BREAKING CHANGE: Pagination now uses cursor-based
pagination instead of offset-based. The page and
per_page query params are replaced by cursor and limit.