Unclear documentation regarding `bump_map`

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.

[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.

[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) $