Breaking Change Commit Messages
Learn how to write commit messages for breaking changes. Covers the ! notation, BREAKING CHANGE footer, migration guidance, and how breaking changes affect versioning.
Detailed Explanation
Breaking Changes in Conventional Commits
A breaking change introduces an incompatible modification to the public API, behavior, or interface. Under Semantic Versioning, any breaking change triggers a major version bump (e.g., 2.1.0 to 3.0.0), regardless of whether it is a feature or a fix.
Two Ways to Signal Breaking Changes
1. Exclamation Mark in Header
Add ! after the type (and scope, if present):
feat!: remove support for Node.js 14
fix(api)!: rename /users endpoint to /accounts
2. BREAKING CHANGE Footer
Add a BREAKING CHANGE: footer with details:
feat: redesign authentication API
BREAKING CHANGE: The login endpoint now returns a JWT token
instead of a session cookie. All clients must update their
authentication flow to use Bearer token headers.
3. Both Together (Recommended)
Using both provides maximum visibility:
feat(auth)!: replace session-based auth with JWT
Migrate from express-session to jsonwebtoken for
stateless authentication. Sessions are no longer
stored on the server.
BREAKING CHANGE: The /auth/login endpoint now returns
{ token: string } instead of setting a session cookie.
Clients must include Authorization: Bearer <token>
header in all authenticated requests.
Migration guide: https://docs.example.com/auth-v3
What Qualifies as a Breaking Change
| Breaking | Not Breaking |
|---|---|
| Removing a public API endpoint | Adding a new endpoint |
| Changing a function's return type | Adding optional parameters |
| Renaming an exported function | Adding a new export |
| Changing default behavior | Adding a configuration option |
| Dropping support for a platform | Adding platform support |
Migration Guidance
Always include clear migration instructions in the body or footer. Tell users:
- What changed and why
- What breaks in their current usage
- How to migrate with specific steps or code examples
- Link to full migration guide if available
Use Case
You are releasing a major version of your library that changes the authentication mechanism from session cookies to JWT tokens. Every consumer of your API needs to update their integration. You need a commit message that clearly signals this as a breaking change, includes migration instructions, and triggers the correct major version bump in your automated release pipeline.