Support filtering commits before version bump calculation in monorepos

[schlotter]

Currently, the regular expression specified for bump_pattern matches the commit message line-by-line. In this way, you can have a commit message where multiple lines match the bump_pattern.

I have a monorepo (code repository with multiple applications), where I want cz bump to filter commit messages based on a custom pattern. At the moment, cz bump uses all commit messages (i.e., it includes commit messages that do not affect the application that I want to bump). In my monorepo, this is not desired because in this way cz bump considers commit messages which are not relevant to the application I want to bump.

In contrast, changelog generation already works for polyrepos with multiple applications: changelog_pattern can match whole commit messages instead of single line, so it is possible to filter out commit messages which are not relevant to the application for which a changelog shall be generated.

I would like to contribute a Pull Request that supports my use case above, but I want to use this discussion here first to find out the best way to go forward.

Options that I see:

1. Change bump_pattern so that full commit messages are analyzed.

   I think this is not feasible because it would break current behavior. In this option, special considerations need to be applied to ensure the current behavior of having more than one entry from bump_map remains effective.

2. Filter commit messages with changelog_pattern first and only bump using bump_pattern for remaining commits.

   In order to not break current behavior, this new behavior could be enabled with a new config option bump_based_on_changelog_pattern (suggestions for name welcome).

3. Filter commit messages with a new pattern first and only bump using bump_pattern for remaining commits.

   This is similar to the previous option, except that the existing option changelog_pattern would not be reused, but instead a new config option for the pattern would be created. A name could be bump_commit_filter_pattern (suggestions welcome). The default value would be a pattern that matches all commit messages, which is unchanged from current behavior.

My preference currently are option 2 and option 3. I lean towards option 3 because I think the new behavior warrants a new config name (changelog_pattern is not directly related to bumping).

Please let me know your thoughts. I would like to see them because I start implementing into a certain direction.

Thank you 🙂

Edit: Changed incorrect wording polyrepo to monorepo in title and body.

[schlotter]

PR #1983 is related because it changes how commit messages are parsed: In find_increment a list candidate_lines is introduced which contains all commit lines which are relevant for bumping. The bump_pattern is then applied only to those lines.

All three options from above remain possible, with option 3 remaining my preference.

[woile]

This is related to #1385
The idea is to introduce new behavior that will let you extend or override the configuration being used. See:
#1385 (comment)

With this, you will be able to define exactly what you want on each .cz.toml on a monorepo.

Minor correction: monorepo -> 1 repository with many apps. polyrepo -> many repos with apps.

[schlotter]

Thank you! #1385 looks like a much larger piece of work. I hope this feature suggestion can be considered independently so that the two efforts do not become coupled and this use case is not blocked by the broader implementation.

I took a look at the linked PR #2006 and was wondering how #1385 would affect the way bump_pattern is evaluated. From what I can see, find_increment() in bump.py is not modified by that PR. Based on that, I would expect bump_pattern to continue being matched line by line against commit messages, even with the proposed extension/overriding functionality.

Am I overlooking something, or is there another part of the #1385 proposal that would change how bump calculation is performed?

PS: Thank you for the correction. I have updated the title and description above to use monorepo instead of polyrepo 😊

[woile]

If you are following this tutorial: https://commitizen-tools.github.io/commitizen/tutorials/monorepo_guidance/

Then I can tell you, at the end of the article, that the suggested changelog_pattern under customize doesn't work.
And also bump_pattern cannot be customized. The functionality is quite limited.

If you have a .cz.toml per application inside your repo, the idea would to be specify a custom bump_pattern and changelog_pattern for each, then. Then each app would be filtering only what they need.

Example for a fictional library-z/.cz.toml, this is what you should be able to adjust:

[tool.commitizen]
version = "0.0.1"
tag_format = "${version}-library-z"
ignored_tag_formats = ["${version}-library-*"] # Avoid noise from other tags
update_changelog_on_bump = true

[tool.commitizen.override]
bump_pattern = "^(?P<change_type>feat|fix|refactor|perf|BREAKING CHANGE)(library-z)(?P<breaking>!)?:"
changelog_pattern = "^(?P<change_type>feat|fix|refactor|perf|BREAKING CHANGE)(library-z)(?P<breaking>!)?:"

[schlotter]

Thank you! I wasn't aware of that document, but we are actually following that guidance 😁

The key difference in our setup is that we do not distinguish applications through the Conventional Commit scope. Instead, we use a custom metadata line in the commit message that starts with Applications:. For example:

-- Commit 1 -----
feat: implement library

Applications: ['AppA', 'AppB']

-- Commit 2 -----
fix: fix nasty bug

Applications: ['AppB']

-- Commit 3 -----
ci: change release pipeline

Applications: ['AppA', 'AppB']

-- Commit 4 -----
...

In this scenario, the approach shown in your tool.commitizen.override example would not be sufficient for us. To determine whether a commit belongs to AppA or AppB, we need to inspect the full commit message, not just the commit title.

For changelog generation, this already works well because changelog_pattern can be matched against the entire commit message. This allows us to include only commits relevant to a specific application. For version bump calculation, however, bump_pattern is currently evaluated line by line, which makes this type of filtering impossible. That is the gap my feature suggestion is trying to address.

My understanding is that this could be implemented independently of #1385:

• Deprecate the cz_customize convention and allow for overriding functionality #1385 would provide the override/extends mechanism, allowing projects to customize settings more easily.
• My proposal would introduce a way to filter commits based on the full commit message before they are considered for bump calculation.

In other words, even if #1385 were fully implemented, I believe there would still be value in a feature that allows bump decisions to be based on commit-message-wide filtering.

Does that interpretation make sense?

[woile]

I understand, and we are open if there's a solution that works