BREAKING CHANGE Footer
How to use the BREAKING CHANGE footer in Conventional Commits to describe breaking changes in detail with a multi-line commit body.
Detailed Explanation
The BREAKING CHANGE Footer
The BREAKING CHANGE footer provides a way to describe a breaking change in detail within the commit body. Unlike the ! marker, which is a single character, the footer allows a full explanation of what changed and how consumers should update their code.
Format
refactor(auth): switch from session cookies to JWT tokens
Migrate the authentication system from server-side sessions
to stateless JWT tokens. All API endpoints now expect a
Bearer token in the Authorization header.
BREAKING CHANGE: API endpoints no longer accept session cookies.
Clients must include a JWT token in the Authorization header.
The /api/session endpoint has been removed.
Structure Breakdown
- Subject line:
refactor(auth): switch from session cookies to JWT tokens - Blank line: Required separator between subject and body.
- Body: Multi-line explanation of the change.
- Blank line: Required separator between body and footer.
- Footer:
BREAKING CHANGE: ...— the breaking change description.
Footer Rules
- The token must be exactly
BREAKING CHANGE(with a space) orBREAKING-CHANGE(with a hyphen). - It is followed by
:(colon and space) and then the description. - The description can span multiple lines.
BREAKING CHANGEis case-sensitive —breaking changeis not recognized.
Combining with !
You can use both the ! marker and the footer:
refactor(auth)!: switch from session cookies to JWT
BREAKING CHANGE: API endpoints no longer accept session cookies.
This gives maximum visibility: the ! is seen in short logs, and the footer provides the full explanation.
Multiple Breaking Changes
If a single commit introduces multiple breaking changes, list them all in the footer or use multiple BREAKING CHANGE lines.
Use Case
Use the BREAKING CHANGE footer when a breaking change requires a detailed explanation. This is common when changing API contracts, removing features, or modifying data formats. The footer gives consumers clear migration instructions directly in the commit history.