feat(rules): add breaking-change-exclamation-mark #4548

adamchristiansen · 2025-09-24T06:39:40Z

Description

A breaking change can be denoted by either ! in the header (e.g., feat!: add advanced search filters) or by including BREAKING CHANGE in the footer (e.g., BREAKING CHANGE: old queries no longer work with the new API.). This pull request adds the breaking-change-exclamation-mark rule that requires a BREAKING CHANGE footer if ! appears in the header and a ! in the header if BREAKING CHANGE appears in the footer. The idea is that it is all or nothing, so if one breaking change marker is present the other must be present too.

Motivation and Context

Implements and closes #4547.

This feature enforces a solution to three problems:

Using just ! might not convey enough information. For example, feat!: add advanced search filters. Why is this a breaking change? How do I know what broke unless the footer is present? Using this rule will fail because a footer indicating a breaking change must be added in this case.
Using just BREAKING CHANGE might cause confusion. For example, if I use something like git log --online to quickly look at changes and I see feat: add advanced search filters, I have no idea that it is a breaking change without looking at that specific commit in greater detail. This rule will fail because an exclamation mark must be added to the head in this case.
This rule enforces the broadest tooling coverage since both means of denoting breaking changes are present in commit messages.

Usage examples

// commitlint.config.js
module.exports = {
  rules: {
    'breaking-change-exclamation-mark': [2, 'always']
  }
};

echo "feat!: add something\n\nBREAKING CHANGE: breaks something" | commitlint # passes
echo "feat: add something" | commitlint # passes
echo "feat!: add something" | commitlint # fails
echo "feat: add something\n\nBREAKING CHANGE: breaks something" | commitlint # fails

How Has This Been Tested?

I added a new test @commitlint/rules/src/breaking-change-exclamation-mark.test.ts that follows the structure of existing tests. The commit messages to tests were decided based on equivalence partitions.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

My change requires a change to the documentation.
I have updated the documentation accordingly.
I have added tests to cover my changes.
All new and existing tests passed.

codesandbox-ci · 2025-09-24T06:40:18Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

JounQin · 2025-09-24T10:19:19Z

@commitlint/rules/src/breaking-change-exclamation-mark.ts

+		return [true];
+	}
+
+	const hasExclamationMark = !!header && /!:/.test(header);


Use breakingHeaderPattern accordingly:

https://github.com/conventional-changelog/conventional-changelog/blob/1552de5434163eb63d3bf73d97bcb3bf34de8586/packages/conventional-changelog-conventionalcommits/src/parser.js#L4

I will make this change.

Should this be updated to use the breakingHeaderPattern too? To me, that is outside of the scope of this pull request and should be a separate commit.

commitlint/@commitlint/rules/src/subject-exclamation-mark.ts

Line 11 in 0735b63

const hasExclamationMark = /!:/.test(input);

Personally I think such tiny change is fine to be inclined in one PR.

I will make the change.

JounQin · 2025-09-24T10:33:03Z

@commitlint/rules/src/breaking-change-exclamation-mark.ts

+	}
+
+	const hasExclamationMark = !!header && /!:/.test(header);
+	const hasBreakingChange = !!footer && /BREAKING[ -]CHANGE:/.test(footer);


We need make sure the footer line starts with BREAKING not only includes?

Agreed. I will modify the regex for a multiline search.

JounQin · 2025-09-24T10:35:13Z

@commitlint/rules/src/breaking-change-exclamation-mark.ts

+import message from "@commitlint/message";
+import { SyncRule } from "@commitlint/types";
+
+export const breakingChangeExclamationMark: SyncRule = (


The new rule should be added into

commitlint/@commitlint/types/src/rules.ts

Line 92 in 0735b63

export type RulesConfig<V = RuleConfigQuality.User> = {

JounQin · 2025-09-25T06:57:09Z

@commitlint/rules/src/index.ts

 import { typeMinLength } from "./type-min-length.js";

 export default {
+	"breaking-change-exclamation-mark": breakingChangeExclamationMark,


Should we resort them alphabetically?

Agreed. I will fix the sorting.

JounQin · 2025-09-25T06:57:33Z

docs/reference/rules.md

@@ -1,5 +1,19 @@
 # Rules

+## breaking-change-exclamation-mark


Same as above about the order.

Agreed again; I will fix this. It has bothered me in the past looking things up on this page as it is about 90% in the right order.

Implements and closes #4547.

@JounQin

Addresses review feedback from @JounQin about pull request #4548. - Use `breakingHeaderPattern` to search for the exclamation mark in the header. - Correct the regular expression to require that BREAKING CHANGE in the footer be anchored at the beginning of a line. - Updated the `RulesConfig` type.

@JounQin

Address pull request feedback from @JounQin. - Fixed regex for `subject-exclamation-mark`. - Fixed sorting for `RulesConfig`. - Fixed sorting for `rules.md`.

adamchristiansen · 2025-09-26T05:09:16Z

I made several pushes because I resolved a conflict with a merge instead of performing a rebase 🤦. I have implemented all suggestions and rebased the branch onto the latest master, so I believe it is ready now.

escapedcat · 2025-10-03T08:31:56Z

Thanks @adamchristiansen !

escapedcat requested a review from JounQin September 24, 2025 08:17

JounQin suggested changes Sep 24, 2025

View reviewed changes

JounQin reviewed Sep 24, 2025

View reviewed changes

JounQin suggested changes Sep 25, 2025

View reviewed changes

adamchristiansen force-pushed the master branch 3 times, most recently from 4ba9f06 to 28e06e1 Compare September 26, 2025 04:48

adamchristiansen added 3 commits September 25, 2025 22:53

feat(rules): add breaking-change-exclamation-mark

c200f4a

Implements and closes #4547.

feat(rules): breaking-change-exclamation-mark pull request feedback

bfab842

Address pull request feedback from @JounQin. - Fixed regex for `subject-exclamation-mark`. - Fixed sorting for `RulesConfig`. - Fixed sorting for `rules.md`.

adamchristiansen force-pushed the master branch from 28e06e1 to bfab842 Compare September 26, 2025 05:02

escapedcat merged commit c4d419b into conventional-changelog:master Oct 3, 2025
12 checks passed

This was referenced Dec 5, 2025

chore(deps): update dependency @commitlint/cli to 20.2.0 stacksjs/bun-plugin-yml#38

Open

chore(deps): update dependency @commitlint/cli to 20.2.0 stacksjs/biome-config#31

Open

feat(rules): add breaking-change-exclamation-mark #4548

feat(rules): add breaking-change-exclamation-mark #4548

Conversation

adamchristiansen commented Sep 24, 2025

Description

Motivation and Context

Usage examples

How Has This Been Tested?

Types of changes

Checklist:

Uh oh!

codesandbox-ci bot commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamchristiansen commented Sep 26, 2025

Uh oh!

escapedcat commented Oct 3, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

codesandbox-ci bot commented Sep 24, 2025 •

edited

Loading