Unclear documentation regarding `bump_map`

[ruancomelli]

Type

• Content inaccurate
• Content missing
• Typo

URL

https://commitizen-tools.github.io/commitizen/customization.html#1-customize-in-configuration-file

TL;DR

How can I configure Commitizen in a pyproject.toml to fix the MAJOR version as 0, increment MINOR on breaking changes and PATCH on any other change as simply as possible?

Description

I am working on a project in early-stage development. In this case, breaking changes happen more often than not. So, to flag this situation, we are using the following convention: the version number is always 0.y.z (which is consistent with SemVer). We increment y when breaking changes happen, and z whenever we introduce new features and bug fixes.

To achieve this, I wrote the following configuration in our pyproject.toml:

[tool.commitizen]
tag_format = "v$major.$minor.$patch$prerelease"
update_changelog_on_bump = true
version = "0.3.2"
bump_map = {break = "MINOR", new = "PATCH", fix = "PATCH", hotfix = "PATCH"}

This seemed pretty straightforward, but, to my surprise, it didn't work. This is what I got after introducing breaking changes to the code:

$ cz bump --dry-run
bump: version 0.3.2 → 1.0.0
tag to create: v1.0.0
increment detected: MAJOR

whereas desired behaviour is to get

$ cz bump --dry-run
bump: version 0.3.2 → 0.4.0
tag to create: v0.4.0
increment detected: MINOR

Well, of course it doesn't work. According to the linked docs, the bump_map configuration should be included in a [tool.commitizen.customize] section of the configuration file. But then I tried this:

[tool.commitizen]
name = "cz_customize"
tag_format = "v$major.$minor.$patch$prerelease"
update_changelog_on_bump = true
version = "0.3.2"

[tool.commitizen.customize]
bump_map = {break = "MINOR", new = "PATCH", fix = "PATCH", hotfix = "PATCH"}

This almost works (note that now the detected change is "PATCH", but it should be "MINOR"):

$ cz bump --dry-run
bump: version 0.3.2 → 0.3.3
tag to create: v0.3.3
increment detected: PATCH

but the problem is that now committing does not work anymore:

$ cz c
Traceback (most recent call last):
  File ".../.venv/bin/cz", line 8, in <module>
    sys.exit(main())
  File ".../.venv/lib/python3.7/site-packages/commitizen/cli.py", line 301, in main
    args.func(conf, vars(args))()
  File ".../.venv/lib/python3.7/site-packages/commitizen/commands/commit.py", line 72, in __call__
    m = self.prompt_commit_questions()
  File ".../.venv/lib/python3.7/site-packages/commitizen/commands/commit.py", line 50, in prompt_commit_questions
    answers = questionary.prompt(questions, style=cz.style)
  File ".../.venv/lib/python3.7/site-packages/questionary/prompt.py", line 68, in prompt
    return unsafe_prompt(questions, answers, patch_stdout, true_color, **kwargs)
  File ".../.venv/lib/python3.7/site-packages/questionary/prompt.py", line 132, in unsafe_prompt
    for question_config in questions:
TypeError: 'NoneType' object is not iterable

But then this raised some questions, which are unanswered in the docs:

• what are the keys in bump_map? Did I write this part of the configuration correctly?
• I assume that the error with cz c is due to the fact that I didn't provide [[tool.commitizen.customize.questions]]. If that's it, how can I provide such sections so that cz c behaves just like before (with the same questions and same options)?
• do I really need to write [[tool.commitizen.customize.questions]]? It seems to me that customizing bump_map should "just work" in the [tool.commitizen] section.
• how (if that's possible at all) can Commitizen be configured using a pyproject.toml configuration file to achieve the desired behaviour as simply as possible, without writing [[tool.commitizen.customize.questions]] sections?
• I also assume that all of this is tightly coupled with Conventional Commits specification. If so, I think that some links here and there in the documentation should at least point users to where they should look for more answers.

I am marking this as a "documentation" issue since it isn't clear to me from the docs if the behaviour I want is even possible, and, if so, how to get it to work.

[woile]

Hey thanks for the finding, I think we should fix the docs, but it also looks like a bug.
Customizing cz should work with the default questions if not found, I agree with you.
What do you think @Lee-W ? I'm not much of an user of cz.customize so not sure if that's how it should behave.
OTOH we could make bump_map as part of the settings.

In the meanwhile you can write the questions, or write a custom cz class to by-pass the issue, sorry.

[Lee-W]

• what are the keys in bump_map? Did I write this part of the configuration correctly?
  It depends on your bump_pattern. Thus, you'll need to add the following configuration

bump_pattern = "^(break|new|fix|hotfix)"

• I assume that the error with cz c is due to the fact that I didn't provide [[tool.commitizen.customize.questions]]. If that's it, how can I provide such sections so that cz c behaves just like before (with the same questions and same options)?

Yes, that's correct. There's no way can support the full functionality through customize at this moment. The main reason is that filter is not yet supported through customize

• do I really need to write [[tool.commitizen.customize.questions]]? It seems to me that customizing bump_map should "just work" in the [tool.commitizen] section.
• how (if that's possible at all) can Commitizen be configured using a pyproject.toml configuration file to achieve the desired behaviour as simply as possible, without writing [[tool.commitizen.customize.questions]] sections?

I think you can try something like

[tool.commitizen]
name = "cz_conventional_commits"
tag_format = "v$major.$minor.$patch$prerelease"
update_changelog_on_bump = true
version = "0.3.2"
bump_map = {break = "MINOR", new = "PATCH", fix = "PATCH", hotfix = "PATCH"}

It uses cz_conventional_commits but you can change the default values.

Edit: I just found out this is not yet supported as well, but I think it much easier to add than supporting filter for cz_customize

• I also assume that all of this is tightly coupled with Conventional Commits specification. If so, I think that some links here and there in the documentation should at least point users to where they should look for more answers.

Could you kindly point out where do you think are the best places to add these links? We're open to pull request as well 🙂

[Lee-W]

@woile

Customizing cz should work with the default questions if not found, I agree with you.

I don't think we need default questions for cz_customize. But we should definitely provide a clear error message. Default questions might not make sense to different customization and might be confusing. We should make it part of settings of cz_conventinoal instead.

OTOH we could make bump_map as part of the settings.

I think this is how this kind of issue should be solved.

[ruancomelli]

Thank you both for your replies!

So I think that, in order to use bump_map the way I wanted to, this parameter should become part of the settings instead of the customizations, right? Moreover, I completely agree that a clear error message should be provided in case no custom questions are defined. Something like adding if questions is None: raise <Nice Error>('custom questions should be provided when customizing Commitizen. See <link to the docs>.') to the right place in the code.

I'm really a newbie to Commitizen, so I have no clue as to where to start fixing this. I am very willing to help, though, so any guidance is appreciated here 😁

@woile
As to the docs, I really don't know where and what to add. Perhaps adding something like "you should always provide custom questions when customizing Commitizen" somewhere in the docs regarding customization would be helpful.

Also, you mentioned that bump_pattern = "^(break|new|fix|hotfix)" would complete my bump_map setting. Do those keys (break, new etc.) have any special meaning to Commitizen, or can I add any keys I wish (for instance bump_pattern = "^(foo|bar)")?

The docs mention that bump_pattern is a

Regex to extract information from commit (subject and body)

could you provide an example for this? How would different bump_patterns extract information from the commit, so that I can customize bump_map correctly?

[Lee-W]

The error can be handled at either commitizen/cz/customize/customize.py#L40 or commitizen/commands/commit.py.

As for the new feature, I think the idea is to load the configuration from commitizen/config/base_config.py to commitizen/cz/conventional_commits/conventional_commits.py.

It seems both we are quite busy these days 😞 But we'd be happy to provide help if you're interested in submitting a pull request 🙂

[jon-nfc]

I have the same issue as above. just wish to customize one part, the bump map. but doing just this causes the other issue as pointed out above, use the defaults if the setting is not available

my .cz.yaml with the desired custom settings

commitizen:
  bump_message: "style(Version): bump version $current_version \u2192 $new_version"
  changelog_incremental: false
  tag_format: v$major.$minor.$patch$prerelease
  update_changelog_on_bump: true
  version: 0.1.0
  name: cz_customize
  customize:
    bump_pattern: "^(break|new|fix|hotfix|ci|docs)"
    bump_map:
      break: MAJOR
      new: MINOR
      fix: PATCH
      hotfix: PATCH
      ci: PATCH
      docs: PATCH

with the custom settings neither changelog or cz commit works anymore.

error from cz commit

(dev_env) $ cz commit
Traceback (most recent call last):
  File "/home/username/tmp/ansible-roles/dev_env/bin/cz", line 8, in <module>
    sys.exit(main())
  File "/home/username/tmp/ansible-roles/dev_env/lib/python3.6/site-packages/commitizen/cli.py", line 301, in main
    args.func(conf, vars(args))()
  File "/home/username/tmp/ansible-roles/dev_env/lib/python3.6/site-packages/commitizen/commands/commit.py", line 72, in __call__
    m = self.prompt_commit_questions()
  File "/home/username/tmp/ansible-roles/dev_env/lib/python3.6/site-packages/commitizen/commands/commit.py", line 50, in prompt_commit_questions
    answers = questionary.prompt(questions, style=cz.style)
  File "/home/username/tmp/ansible-roles/dev_env/lib/python3.6/site-packages/questionary/prompt.py", line 68, in prompt
    return unsafe_prompt(questions, answers, patch_stdout, true_color, **kwargs)
  File "/home/username/tmp/ansible-roles/dev_env/lib/python3.6/site-packages/questionary/prompt.py", line 132, in unsafe_prompt
    for question_config in questions:
TypeError: 'NoneType' object is not iterable
(dev_env) $

[Lee-W]

Yes, the problem is that we do not have default questions as of now. We're planning on make cz rules (e.g., conventional commit) customizable but will most likely keep cz_customize as it is now

[xytian315]

@Lee-W when I do the customize config like this:

bump_pattern = "^(break|new|fix|hotfix|ci)"
changelog_pattern = "^(break|new|fix|hotfix|ci)"

And I have a commit like "ci: changed ci". Then when I run cz ch, the changelog doesn't include ci commit. Is this not supported?

[jon-nfc]

@Lee-W when I do the customize config like this:

bump_pattern = "^(break|new|fix|hotfix|ci)"
changelog_pattern = "^(break|new|fix|hotfix|ci)"

And I have a commit like "ci: changed ci". Then when I run cz ch, the changelog doesn't include ci commit. Is this not supported?

@xytian315 you have to create a python module. please see this module on how I did it. I added ci and docs plus the git commit to the changleog.