diff --git a/commitizen/cz/conventional_commits/conventional_commits.py b/commitizen/cz/conventional_commits/conventional_commits.py index 31c329595..185aaa3cf 100644 --- a/commitizen/cz/conventional_commits/conventional_commits.py +++ b/commitizen/cz/conventional_commits/conventional_commits.py @@ -62,7 +62,10 @@ def questions(self) -> list[CzQuestion]: }, { "value": "docs", - "name": "docs: Documentation only changes", + "name": ( + "docs: Documentation only changes. " + "Correlates with no version bump in SemVer" + ), "key": "d", }, { @@ -70,7 +73,8 @@ def questions(self) -> list[CzQuestion]: "name": ( "style: Changes that do not affect the " "meaning of the code (white-space, formatting," - " missing semi-colons, etc)" + " missing semi-colons, etc). " + "Correlates with no version bump in SemVer" ), "key": "s", }, @@ -78,25 +82,33 @@ def questions(self) -> list[CzQuestion]: "value": "refactor", "name": ( "refactor: A code change that neither fixes " - "a bug nor adds a feature" + "a bug nor adds a feature. " + "Correlates with PATCH in SemVer" ), "key": "r", }, { "value": "perf", - "name": "perf: A code change that improves performance", + "name": ( + "perf: A code change that improves performance. " + "Correlates with PATCH in SemVer" + ), "key": "p", }, { "value": "test", - "name": ("test: Adding missing or correcting existing tests"), + "name": ( + "test: Adding missing or correcting existing tests. " + "Correlates with no version bump in SemVer" + ), "key": "t", }, { "value": "build", "name": ( "build: Changes that affect the build system or " - "external dependencies (example scopes: pip, docker, npm)" + "external dependencies (example scopes: pip, docker, npm). " + "Correlates with no version bump in SemVer" ), "key": "b", }, @@ -104,7 +116,8 @@ def questions(self) -> list[CzQuestion]: "value": "ci", "name": ( "ci: Changes to CI configuration files and " - "scripts (example scopes: GitLabCI)" + "scripts (example scopes: GitLabCI). " + "Correlates with no version bump in SemVer" ), "key": "c", }, diff --git a/commitizen/cz/conventional_commits/conventional_commits_info.txt b/commitizen/cz/conventional_commits/conventional_commits_info.txt index a076e4f5e..9df2151e7 100644 --- a/commitizen/cz/conventional_commits/conventional_commits_info.txt +++ b/commitizen/cz/conventional_commits/conventional_commits_info.txt @@ -15,12 +15,17 @@ A BREAKING CHANGE can be part of commits of any type. Others: commit types other than fix: and feat: are allowed, like chore:, docs:, style:, refactor:, perf:, test:, and others. -We also recommend improvement for commits that improve a current -implementation without adding a new feature or fixing a bug. - Notice these types are not mandated by the conventional commits specification, and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE). +Commitizen extends this set with sensible defaults: by default, refactor: and perf: +correlate with PATCH in semantic versioning, while docs:, style:, test:, build:, ci:, +and other types do not bump the version (unless they include a BREAKING CHANGE). +These defaults can be customized via the `bump_map` and `bump_pattern` settings. + +We also recommend improvement for commits that improve a current +implementation without adding a new feature or fixing a bug. + A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays. diff --git a/docs/commands/bump.md b/docs/commands/bump.md index 84666cbc6..63ddf7f9c 100644 --- a/docs/commands/bump.md +++ b/docs/commands/bump.md @@ -30,6 +30,11 @@ The version follows the `MAJOR.MINOR.PATCH` format, with increments determined b | `MINOR` | New features | `feat` | | `PATCH` | Fixes and improvements | `fix`, `perf`, `refactor`| +Other Conventional Commit types recognized by Commitizen (such as `docs`, `style`, `test`, `build`, `ci`, and `chore`) do not bump the version unless they include a `BREAKING CHANGE`. You can customize this behavior with the [`bump_map`](../config/bump.md) and [`bump_pattern`](../config/bump.md) settings. + +!!! tip "Recommended reading on versioning" + For background on the strengths and limitations of semantic versioning, and on alternative versioning strategies, see the [Recommended Reading on Versioning](../external_links.md#recommended-reading-on-versioning). + ## Command line options ![cz bump --help](../images/cli_help/cz_bump___help.svg) diff --git a/docs/external_links.md b/docs/external_links.md index dc9bc1b0a..efe8d8ce8 100644 --- a/docs/external_links.md +++ b/docs/external_links.md @@ -16,4 +16,23 @@ - [How to Write Better Git Commit Messages – A Step-By-Step Guide](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/?utm_source=tldrnewsletter) (English) - [Continuous delivery made easy (in Python)](https://blog.devgenius.io/continuous-delivery-made-easy-in-python-c085e9c82e69) +## Recommended Reading on Versioning + +The following articles, surfaced in the discussion of [issue #515][issue-515], +provide useful background on the strengths and limitations of semantic +versioning and on alternative versioning strategies. They can help calibrate +expectations about what a version bump can — and cannot — guarantee to +downstream consumers. + +- [Semantic Versioning Will Not Save You](https://hynek.me/articles/semver-will-not-save-you/) by Hynek Schlawack +- [Why I don't like SemVer anymore](https://snarky.ca/why-i-dont-like-semver/) by Brett Cannon +- [Versioning Software](https://caremad.io/posts/2016/02/versioning-software/) by Donald Stufft +- [Hyrum's Law](https://www.hyrumslaw.com/) — on implicit behavioral contracts beyond the documented API +- [0ver — Zero-based Versioning](https://0ver.org/) +- [CalVer — Calendar Versioning](https://calver.org/) +- [PEP 440 — Version Identification and Dependency Specification](https://peps.python.org/pep-0440/) +- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) +- [Semantic Versioning 2.0.0](https://semver.org/) + [automatizando]: https://youtu.be/t3aE2M8UPBo +[issue-515]: https://github.com/commitizen-tools/commitizen/issues/515