Breaking Change with ! Marker
How to indicate a breaking change using the ! marker in Conventional Commits. Learn the correct placement and what triggers a major version bump.
Detailed Explanation
The ! Breaking Change Marker
The exclamation mark (!) is a concise way to indicate that a commit introduces a breaking change. It is placed immediately before the colon separator, after the type and optional scope.
Format
feat!: remove deprecated getUserByName API
feat(api)!: change authentication response format
Version Impact
A breaking change triggers a major version bump in semantic versioning (e.g., 1.2.3 to 2.0.0). This is the most significant version change and signals to consumers that they need to update their code.
Placement Rules
The ! must be placed:
- After the type:
feat! - After the scope (if present):
feat(api)! - Before the colon:
feat!: ...
Invalid placements:
!feat: ...— before the typefeat: !description— in the descriptionfeat!(api): ...— between type and scope
! vs BREAKING CHANGE Footer
Both methods are valid for indicating breaking changes:
feat!: remove deprecated API
is equivalent to:
feat: remove deprecated API
BREAKING CHANGE: the getUserByName endpoint has been removed
The ! marker is more concise and visible in single-line commit logs. The footer approach allows a detailed explanation of the breaking change. You can use both together for maximum clarity.
When to Use Breaking Changes
Mark a commit as breaking when it:
- Removes a public API endpoint or method
- Changes the signature of a public function
- Modifies the format of configuration files
- Alters the behavior of existing functionality in incompatible ways
- Drops support for a platform, runtime, or dependency version
Use Case
Use the ! marker when you want a concise, visible indication of a breaking change in single-line commit logs. It is ideal for small breaking changes where the commit description itself explains the impact. For complex breaking changes, combine it with a BREAKING CHANGE footer.