Content to be added or fixed

Type

• Content inaccurate

URL

https://commitizen-tools.github.io/commitizen/bump/

Description

Problem

The docs state “fix+everything else” bumps PATCH of the version string per the default commit_map.

However, this is not the case:

https://github.com/commitizen-tools/commitizen/blob/79165119817cbd0aef25434a85dcbffa3a13acbb/commitizen/defaults.py#L78-L80

Only fix, refactor, and perf bump PATCH, leaving out docs, style, test, build, and ci, which don’t bump any part of the version.

Not only are the docs incorrect, but this is out of step with Conventional Commits 1.0.0. Additional commit types are permitted by the specification (e.g. commitizen appears to be using the Angular Convention by default), but no guidance on version bumping is given for these addition types. Where a commit type bumps or does not bump a version, this should be explicitly stated (e.g. the commit message instructions for fix has Correlates with PATCH in SemVer, but not refactor or perf, leaving one to believe these do nothing).

Recommendations:

1. (PREFERRED; Conventional Commit spec): Only feature and fix should be in the default commit_map per Conventional Commits 1.0.0. refactor and perf should not bump PATCH. The Angular types refactor, perf, docs, style, test, build, and ci should be removed from the default commit types.

2. (ALTERNATIVE; Angular Convention, but with explicit messaging): refactor and perf should not bump PATCH. The commit message instructions for refactor, perf, docs, style, test, build, and ci should add Correlates with no version bump in SemVer. In addition, the docs should clearly state the Angular Convention commit types are included in cz c by default.

Tasks:

• Correct the documentation (state what change types bump versions and that commitizen includes Angular Convention types by default)
• Add notes in commit message instructions to identify what version bump occurs with all change types (e.g. Correlates with no version bump in SemVer)

[adam-grant-hendry]

@woile @Lee-W I’ve had some time to investigate and practice with semver and found some additional articles that have changed my opinions a bit.

The following are several great articles related to semantic versioning (perhaps well-known by now):

• Semantic Versioning Will Not Save You, by Hynek Schlawack
• Why I don’t like SemVer anymore, by Brett Cannon
• Versioning Software, by Donald Stufft

These articles opened my eyes to Hyrum’s Law, which indicates you cannot guarantee a priori what changes will break end-user code. You can only guarantee what changes will break your API (i.e. how you claim your library is intended to be used) up to the tests contained within your test suite. This has significant implications for dependency managers (like poetry) that implicitly rely on semver being a reliable outward-facing contract to end-users to identify what will break their code.

The above has been a source of tension in the community:

• e.g., poetry binds major versions, which was quite a divisive choice on the developers’ part (consequences of pinning major versions is explained in Hynek’s article).
• 0ver has become a popular versioning strategy for several libraries
• PEP 440 supports the 0ver schema, as Brett mentions
• CalVer is also another popularly used alternative

The comment I like the most is Brett Cannon’s epiphany:

version numbers are just a mapping of a sequence of digits to our branching strategy in source control

What is understated here is that the community implicitly understands major versions to be long-lived branches. When a v1 is released, the implicit statement to end users is:

• The current API is stable enough and relied upon by a sufficient number of users to warrant long-term maintenance
• The maintainers will submit patches, bug fixes, hot fixes, etc., for this branch
• There is an implicit release schedule, beyond which this branch will be sunset/deprecated and support will no longer be available

I believe the commitizen documentation should make explicit that semver cannot guarantee whether or not a different version of installed software will break end-user code, but the notions of BREAKING, feat, fix, etc., should be understood within the context of the library by itself, without other libraries, as tested by the project test suite.

For example, this is how library maintainers should treat the following and understand their end-user contract to be:

“Any change made to this library may break end-user code at any time. We can only guarantee which changes are breaking and non-breaking solely within the context of the usage of this library by itself, as documented in the API, both up to and limited by the comprehensiveness of this library’s test suite.”

• feat: We have added a feature to this library that previously did not exist. We have tested it and it does not break our API, but it may break your code.
• fix: We have fixed something that did not work as prescribed in our API. We have tested it and it does not break the original intended usage of our API, but it may break how you’re using it.
• BREAKING: We have either added a feature or fixed something that alters the original intended usage of the API. This may or may not break your code.

Intended as used above means “what is/was intended by the developer(s)” and any change (feat, fix, BREAKING, or otherwise) may or may not break your code.

Donald states this well:

At the end of the day, the most important, but often overlooked, aspect of the version is that one of it’s primary purposes is to communicate with the end users of the software. It’s up to the project what information is most important to their end users that it deserves to be communicated through the version number, though I would suggest that for most projects, SemVer-ish is likely to be best suited.

Additional Excellent Points

Hynek:

In almost 20 years of professional software development I have observed that the amount of unintentional breakage through updates outweighs the amount of intentional breakage by far.

[adam-grant-hendry]

@Lee-W @Woile Lastly, I also want to say “THANK YOU!!!” for this great package! 🎉

Below is my pyproject.toml using standard commitizen (no emojis) that meets what I’ve been talking about above (it would be nice to add a section to your docs containing third-party config files, in addition to 3rd-party packages, since not everyone will want to make a package; granted, some things require a plugin and not everything can be done through a config file). Some things worth noting:

1. Version 2.20.0 does not have the commit_parser option, which is necessary for CHANGELOG.md to be properly rendered. Your docs don’t have a version attached to them, so I am only able to see docs for the latest version (important, say, for those reverting to version 2.20.0 due to Issue #510 ). So, I bumped back up to 2.27.0.

2. It would be nice to have an option added that generates a CHANGELOG.md header (with markdownlint without a header, you get an MD041 error. This is what I have (borrowed from Keep a Changelog):

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to 
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

Since this project adheres to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), the change types
here match those in the commit messages:

- `Feat` for added/removed/deprecated features
- `Fix` for changed/modified items
- `Refactor` for changes not affecting behavior

1. It would be nice if there was a way to customize a third-party plugin. For instance, it would be nice if I could customize commitizen_emoji without having to create a separate plugin.

My TOML Configuration:

[tool.commitizen]
name = "cz_customize"
version = "0.2.0"
version_files = [
    "my_proj/__version__.py",
    "pyproject.toml:version"
]
update_changelog_on_bump = true
changelog_start_rev = '0.2.0'
annotated_tag = true
tag_format = "$version"

[tool.commitizen.customize]
message_template = "{{change_type}}({{scope}}){% if is_breaking_change == true %}!{% endif %}: {{subject}}{% if body %}\n\n{{body}}{% endif %}{% if footer %}\n\n{% if is_breaking_change == true %}BREAKING CHANGE: {% endif %}{{footer}}{% endif %}"
schema_pattern = '(feat|fix|refactor|bump)(\(\S+\))?!?:(\s.*)'
bump_pattern = '^(feat|fix)(\(.+\))?(!)?'
bump_map = { break = "MAJOR", feat = "MINOR", fix = "PATCH" }
change_type_order = ["BREAKING CHANGE", "feat", "fix"]
commit_parser = '(?P<change_type>feat|fix|refactor)(?:\((?P<scope>[^()\r\n]*)\)|\()?(?P<breaking>!)?:\s(?P<message>.*)?'
changelog_pattern = '^(feat|fix|refactor)?(!)?'

[[toml.commitizen.customize.change_type_map]]
"feat" = "Feat"
"fix" = "Fix"
"refactor" = "Refactor"

[[tool.commitizen.customize.questions]]
name = "change_type"
type = "list"
message = "Select the type of change you are committing"
choices = [
    { value = "feat", name = "feat: (Bumps MINOR) Add/remove an item/feature" },
    { value = "fix", name = "fix: (Bumps PATCH) Fix/modify an existing item/feature" },
    { value = "refactor", name = "refactor: (Bumps nothing) Reorganizes item(s); not a 'feat' or 'fix'" },
]

[[tool.commitizen.customize.questions]]
name = "scope"
type = "input"
message = "Scope. Enter the scope of the change, category first (docs/test/ci/build/perf), followed by class or file name if applicable (comma-separted, no spaces):\n"

[[tool.commitizen.customize.questions]]
name = "subject"
type = "input"
message = "Subject. Enter the short summary of the change (imperative tone, lowercase, no period):\n"

[[tool.commitizen.customize.questions]]
name = "is_breaking_change"
type = "confirm"
message = "Is this a BREAKING CHANGE (backwards incompatible)? (Bumps MAJOR; default: N):\n"
default = false

[[tool.commitizen.customize.questions]]
name = "body"
type = "input"
message = "Body. Enter complete details about the change (use full sentences with proper grammar): (press [enter] to skip):\n"

[[tool.commitizen.customize.questions]]
name = "footer"
type = "input"
message = "Footer. Reference any Issues this change addresses. If a BREAKING CHANGE, enter details. (press [enter] to skip):\n"