fix: add custom_major_increment_regex for breaking change detection by jdx · Pull Request #545 · jdx/usage

jdx · 2026-03-13T14:24:36Z

Summary

breaking_always_bump_major from fix: bump major version for breaking changes in release automation #544 didn't work — git cliff --bumped-version still returned v2.18.3 instead of v3.0.0
Adds custom_major_increment_regex to explicitly match the ! breaking change indicator in conventional commits (feat!:, feat(scope)!:, etc.)
This is a belt-and-suspenders fix alongside breaking_always_bump_major

Follow-up to #544

Test plan

After merge, verify release automation updates PR chore: release v3.0.0 #527 to v3.0.0

🤖 Generated with Claude Code

Note

Low Risk
Low risk config-only change that affects version bumping; main risk is unintended major bumps if the regex matches more commit messages than expected.

Overview
Adjusts git-cliff bumping behavior to more reliably detect breaking changes from conventional commits.

Adds custom_major_increment_regex in cliff.toml to explicitly treat feat!: / type(scope)!: style messages as major-version increments, complementing breaking_always_bump_major.

^{Written by Cursor Bugbot for commit e77f510. This will update automatically on new commits. Configure here.}

breaking_always_bump_major alone didn't trigger major bumps for commits using the conventional commit `!` marker. Add an explicit regex to match `type!:` and `type(scope)!:` patterns. Co-Authored-By: Claude Opus 4.6 <[email protected]>

gemini-code-assist · 2026-03-13T14:24:50Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the version bumping logic to correctly identify and apply major version increments when breaking changes are present in commit messages. It addresses a limitation where the existing breaking_always_bump_major setting was insufficient, by adding a custom regular expression to reliably detect the conventional commit ! marker, ensuring that release automation produces the intended major version bumps.

Highlights

Breaking Change Detection Fix: Resolved an issue where breaking_always_bump_major was not correctly triggering major version increments, leading to incorrect version bumps (e.g., v2.18.3 instead of v3.0.0).
Custom Major Increment Regex: Introduced custom_major_increment_regex to explicitly match the ! breaking change indicator in conventional commit messages (e.g., feat!:, feat(scope)!:).
Robustness: Implemented this as a complementary fix alongside breaking_always_bump_major to ensure reliable detection of breaking changes.

Activity

This pull request is a follow-up to fix: bump major version for breaking changes in release automation #544.
A test plan is in place to verify release automation updates PR chore: release v3.0.0 #527 to v3.0.0 after this merge.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request adds a custom_major_increment_regex to cliff.toml to more explicitly detect breaking changes from conventional commit messages. This is a good "belt-and-suspenders" approach to ensure major version bumps happen correctly. I've suggested a small refinement to the regex to align it more closely with the existing commit_parsers configuration in the same file, ensuring consistency in how different commit types are handled.

gemini-code-assist · 2026-03-13T14:25:45Z

 # Detect breaking changes from conventional commit `!` marker and footer
 breaking_always_bump_major = true
+# Also match the `!` breaking change indicator in commit messages directly
+custom_major_increment_regex = "^(feat|fix|refactor|perf|chore|style|test|docs)(!|\\(.*\\)!):"


This regex is a good addition to ensure breaking changes are detected. I've noticed a couple of minor inconsistencies with the commit_parsers configuration in this file:

This regex uses docs, while the parser at line 101 uses doc.

The parser at line 105 includes revert, but it's missing from this regex. Revert commits can also be breaking changes.

To make this more consistent with the rest of the configuration, I suggest updating the regex to include revert and use doc instead of docs.

custom_major_increment_regex = "^(feat|fix|refactor|perf|chore|style|test|doc|revert)(!|\\(.*\\))!:"

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

cursor · 2026-03-13T14:29:39Z

 # Detect breaking changes from conventional commit `!` marker and footer
 breaking_always_bump_major = true
+# Also match the `!` breaking change indicator in commit messages directly
+custom_major_increment_regex = "^(feat|fix|refactor|perf|chore|style|test|docs)(!|\\(.*\\)!):"


Regex missing revert type present in commit parsers

Low Severity

The custom_major_increment_regex type list omits revert, even though commit_parsers explicitly handles ^[Rr]evert commits (line 105). Since the PR states breaking_always_bump_major doesn't work, this regex is the primary breaking-change detection mechanism. A revert!: commit would be classified as a Revert in the changelog but would fail to trigger a major version bump.

Additional Locations (1)

cliff.toml#L104-L105

greptile-apps · 2026-03-13T14:30:02Z

Greptile Summary

This PR adds a [bump] section to cliff.toml with two complementary settings intended to ensure git cliff --bumped-version returns v3.0.0 after the breaking-change commit introduced in #542. The two settings — breaking_always_bump_major = true and custom_major_increment_regex — integrate directly with the tasks/release-plz script, which calls git cliff --bumped-version on line 18 to drive semantic versioning.

Key changes:

breaking_always_bump_major = true: instructs git-cliff to always bump the major version whenever its internal conventional-commit parser marks a commit as a breaking change (via ! marker or BREAKING CHANGE: footer)
custom_major_increment_regex: provides a secondary, regex-based path for detecting major-bump candidates, covering feat!: and feat(scope)!: patterns

Concern: The one commit that actually needs to be detected — 9fcfcb7 feat!(spec): add support for license, before/after help metadata — uses the non-standard feat!(scope): ordering (the ! appears before the scope, not after it). The regex ^(feat|fix|refactor|perf|chore|style|test|docs)(!|\(.*\)!): does not match this form. The fix may still work end-to-end if breaking_always_bump_major causes git-cliff's internal parser to handle the !-before-scope case, but that path is less certain and is worth verifying after merge.

Confidence Score: 3/5

Safe to merge as a config-only change, but the primary regression concern (v3.0.0 not being produced) may not be fully resolved.
The TOML syntax is valid, both git-cliff options are legitimate, and the change is confined to configuration. However, the custom_major_increment_regex does not match the non-standard feat!(scope): format used in the specific breaking-change commit (9fcfcb7) that motivated this PR. The fix depends on breaking_always_bump_major successfully triggering through git-cliff's internal parser — which is the path that previously failed in fix: bump major version for breaking changes in release automation #544. Without a concrete test showing git cliff --bumped-version now returns v3.0.0 locally, there is reasonable uncertainty about whether this fully resolves the issue.
cliff.toml — specifically custom_major_increment_regex on line 129

Important Files Changed

Filename	Overview
cliff.toml	Adds `[bump]` section with `breaking_always_bump_major = true` and `custom_major_increment_regex`; the regex handles standard `feat!:` and `feat(scope)!:` but misses the non-standard `feat!(scope):` format used in the commit that originally required a v3.0.0 bump.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["git cliff --bumped-version\n(called in tasks/release-plz line 18)"] --> B{Scan commit history}
    B --> C[Parse each commit\nwith conventional-commit parser]
    C --> D{breaking: true\ndetected by parser?}
    D -- yes --> E["breaking_always_bump_major = true\n→ force major bump"]
    D -- no --> F{Match commit message\nagainst custom_major_increment_regex}
    F -- matches --> E
    F -- no match --> G{Any feat: commit?}
    G -- yes --> H[Bump minor]
    G -- no --> I[Bump patch]
    E --> J["Output: v3.0.0 ✅"]
    H --> K["Output: v2.x.0"]
    I --> L["Output: v2.18.x"]

    style E fill:#4caf50,color:#fff
    style J fill:#4caf50,color:#fff
    style F fill:#ff9800,color:#fff

_{Last reviewed commit: e77f510}

greptile-apps · 2026-03-13T14:30:06Z

 # Detect breaking changes from conventional commit `!` marker and footer
 breaking_always_bump_major = true
+# Also match the `!` breaking change indicator in commit messages directly
+custom_major_increment_regex = "^(feat|fix|refactor|perf|chore|style|test|docs)(!|\\(.*\\)!):"


Regex misses feat!(scope): format — the pattern that triggered this fix

The regex ^(feat|fix|refactor|perf|chore|style|test|docs)(!|\(.*\)!): only handles two standard conventional-commit forms:

feat!: — breaking, no scope

feat(scope)!: — breaking, scope before !

However, the commit that actually needs to be detected as a breaking change is 9fcfcb7 feat!(spec): add support for license, before/after help metadata — the ! appears after the type but before the scope (feat!(spec):). This non-standard ordering is not matched by either alternative in (!|\(.*\)!).

Trace through the regex for feat!(spec)::

feat — matches

(!|\(.*\)!) against !(spec):

Alt 1 ! matches !, but then : is required and ( follows → fails

Alt 2 \(.*\)! requires ( first, but ! follows → fails

→ no match

breaking_always_bump_major = true may still save the day if git-cliff's internal parser recognises the non-standard ! position, but if you want the regex to also cover this format, add a third alternative:

Suggested change

custom_major_increment_regex = "^(feat|fix|refactor|perf|chore|style|test|docs)(!|\\(.*\\)!):"

custom_major_increment_regex = "^(feat|fix|refactor|perf|chore|style|test|docs)(!|\\(.*\\)!|!\\(.*\\)):"

With !\\(.*\\) added, feat!(spec): would match via the new third alternative.

@jdx

⚠️ **CAUTION: this is a major update, indicating a breaking change!** ⚠️ This MR contains the following updates: | Package | Update | Change | |---|---|---| | [usage](https://github.com/jdx/usage) | major | `2.18.2` → `3.2.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>jdx/usage (usage)</summary> ### [`v3.2.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#320---2026-03-23) [Compare Source](jdx/usage@v3.1.0...v3.2.0) ##### 🚀 Features - Support env-backed choices with `choices env=...` by [@mustafa0x](https://github.com/mustafa0x) in [#548](jdx/usage#548) ##### 🐛 Bug Fixes - **(zsh)** escape parentheses and brackets in completion descriptions by [@jdx](https://github.com/jdx) in [#559](jdx/usage#559) ##### New Contributors - [@mustafa0x](https://github.com/mustafa0x) made their first contribution in [#548](jdx/usage#548) ### [`v3.1.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#310---2026-03-22) [Compare Source](jdx/usage@v3.0.0...v3.1.0) ##### 🚀 Features - **(cli)** render all doc-related fields in --help output by [@jdx](https://github.com/jdx) in [#554](jdx/usage#554) - **(cli)** support reading spec from stdin via --file - by [@jdx](https://github.com/jdx) in [#555](jdx/usage#555) ##### 🐛 Bug Fixes - **(zsh)** remove trailing space from completions and add directory slash by [@jdx](https://github.com/jdx) in [#556](jdx/usage#556) - use field assignment for non-exhaustive Spec in benchmarks by [@jdx](https://github.com/jdx) in [#552](jdx/usage#552) ##### 📦️ Dependency Updates - update apple-actions/import-codesign-certs digest to [`fe74d46`](jdx/usage@fe74d46) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#550](jdx/usage#550) - update codecov/codecov-action digest to [`1af5884`](jdx/usage@1af5884) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#551](jdx/usage#551) - lock file maintenance by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#547](jdx/usage#547) ### [`v3.0.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#300---2026-03-13) [Compare Source](jdx/usage@v2.18.2...v3.0.0) ##### 🚀 Features - **(spec)** **breaking** add support for license, before/after help metadata by [@jdx](https://github.com/jdx) in [#542](jdx/usage#542) ##### 🐛 Bug Fixes - **(cobra)** escape newlines, tabs, and carriage returns in kdlQuoteAlways by [@thecodesmith](https://github.com/thecodesmith) in [#539](jdx/usage#539) - bump major version for breaking changes in release automation by [@jdx](https://github.com/jdx) in [#544](jdx/usage#544) - add custom\_major\_increment\_regex for breaking change detection by [@jdx](https://github.com/jdx) in [#545](jdx/usage#545) - handle all breaking change commit formats in major bump regex by [@jdx](https://github.com/jdx) in [27e1ab1](jdx/usage@27e1ab1) - normalize breaking change commit format in preprocessor by [@jdx](https://github.com/jdx) in [aa72b92](jdx/usage@aa72b92) ##### 📚 Documentation - add argparse-usage integration by [@jdx](https://github.com/jdx) in [#531](jdx/usage#531) - mark KDL code blocks as KDL and use correct inline-comment `//` by [@muzimuzhi](https://github.com/muzimuzhi) in [#536](jdx/usage#536) - fix include syntax to match implementation by [@jdx](https://github.com/jdx) in [#540](jdx/usage#540) - consolidate integration list to single source by [@jdx](https://github.com/jdx) in [#541](jdx/usage#541) - fix link to integrations by [@muzimuzhi](https://github.com/muzimuzhi) in [#543](jdx/usage#543) ##### 🛡️ Security - **(deps)** update dependency eslint to v10 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#526](jdx/usage#526) ##### 🔍 Other Changes - Added an integration with ruby's OptionParser by [@packrat386](https://github.com/packrat386) in [#533](jdx/usage#533) ##### 📦️ Dependency Updates - update actions/setup-node digest to [`53b8394`](jdx/usage@53b8394) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#525](jdx/usage#525) - update jdx/mise-action action to v3 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#528](jdx/usage#528) - update rust crate roff to v1 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#529](jdx/usage#529) ##### New Contributors - [@thecodesmith](https://github.com/thecodesmith) made their first contribution in [#539](jdx/usage#539) - [@packrat386](https://github.com/packrat386) made their first contribution in [#533](jdx/usage#533) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

jdx force-pushed the fix/cliff-breaking-version branch from a06029f to e77f510 Compare March 13, 2026 14:24

gemini-code-assist Bot reviewed Mar 13, 2026

View reviewed changes

cursor Bot reviewed Mar 13, 2026

View reviewed changes

greptile-apps Bot reviewed Mar 13, 2026

View reviewed changes

jdx merged commit 2e3fca0 into main Mar 13, 2026
6 of 8 checks passed

jdx deleted the fix/cliff-breaking-version branch March 13, 2026 14:30

mise-en-dev mentioned this pull request Mar 13, 2026

chore: release v3.0.0 #527

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: add custom_major_increment_regex for breaking change detection#545

fix: add custom_major_increment_regex for breaking change detection#545
jdx merged 1 commit intomainfrom
fix/cliff-breaking-version

jdx commented Mar 13, 2026 •

edited by cursor Bot

Loading

Uh oh!

gemini-code-assist Bot commented Mar 13, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Mar 13, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Mar 13, 2026

Uh oh!

greptile-apps Bot commented Mar 13, 2026

Uh oh!

greptile-apps Bot Mar 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	custom_major_increment_regex = "^(feat\|fix\|refactor\|perf\|chore\|style\|test\|docs)(!\|\\(.*\\)!):"
	custom_major_increment_regex = "^(feat\|fix\|refactor\|perf\|chore\|style\|test\|docs)(!\|\\(.\\)!\|!\\(.\\)):"

Uh oh!

Conversation

jdx commented Mar 13, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

gemini-code-assist Bot commented Mar 13, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Mar 13, 2026

Choose a reason for hiding this comment

Regex missing revert type present in commit parsers

Uh oh!

greptile-apps Bot commented Mar 13, 2026

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jdx commented Mar 13, 2026 •

edited by cursor Bot

Loading

Regex missing `revert` type present in commit parsers