Breaking Changes in Changelogs

Detecting Breaking Changes

Breaking changes are the most critical items in any changelog. They tell consumers of your software that upgrading will require modifications to their code, configuration, or workflows. The Changelog Generator detects breaking changes in two ways.

Method 1: The Exclamation Mark

Adding ! before the colon signals a breaking change:

feat(api)!: change response format for /users endpoint
fix!: rename config key from "db_url" to "database_url"

The ! can appear after any type and optional scope. The generator strips the ! during parsing and flags the commit as breaking.

Method 2: BREAKING CHANGE Footer

The Conventional Commits specification also supports a footer notation:

feat(api): change response format

BREAKING CHANGE: The /users endpoint now returns an array
instead of an object. Update all API consumers.

The generator scans each line for the text BREAKING CHANGE or BREAKING-CHANGE (case-insensitive) and flags matching commits.

How Breaking Changes Are Rendered

Detected breaking changes are promoted to a dedicated section at the top of the changelog, before all type-grouped sections:

## [2.0.0] - 2026-02-27

### BREAKING CHANGES
- **api:** change response format for /users endpoint
- rename config key from "db_url" to "database_url"

### Added
- add new pagination system

Semantic Versioning Implications

Under Semantic Versioning, any breaking change requires a major version bump (e.g., 1.x.x to 2.0.0). The prominent placement of breaking changes in the changelog serves as both documentation and a warning to upgraders.