docs(conventional_commits): clarify version bump per commit type

Closes #515

* Update the cz commit prompt to state the version bump impact for every
  Conventional Commit type (refactor/perf correlate with PATCH; docs,
  style, test, build and ci do not bump unless they include a
  BREAKING CHANGE), matching the existing notes for fix and feat.
* Update conventional_commits_info.txt to call out commitizen's defaults
  on top of the Conventional Commits specification.
* Add a "Recommended Reading on Versioning" section in
  docs/external_links.md with the articles surfaced in the issue
  discussion (Hynek, Brett Cannon, Donald Stufft, Hyrum's Law, 0ver,
  CalVer) and cross-link it from docs/commands/bump.md.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: bearomorphism

commitizen/cz/conventional_commits/conventional_commits.py

@@ -62,49 +62,62 @@ def questions(self) -> list[CzQuestion]:
                     },
                     {
                         "value": "docs",
-                        "name": "docs: Documentation only changes",
+                        "name": (
+                            "docs: Documentation only changes. "
+                            "No version bump (unless BREAKING CHANGE)"
+                        ),
                         "key": "d",
                     },
                     {
                         "value": "style",
                         "name": (
                             "style: Changes that do not affect the "
                             "meaning of the code (white-space, formatting,"
-                            " missing semi-colons, etc)"
+                            " missing semi-colons, etc). "
+                            "No version bump (unless BREAKING CHANGE)"
                         ),
                         "key": "s",
                     },
                     {
                         "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. "
+                            "No version bump (unless BREAKING CHANGE)"
+                        ),
                         "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). "
+                            "No version bump (unless BREAKING CHANGE)"
                         ),
                         "key": "b",
                     },
                     {
                         "value": "ci",
                         "name": (
                             "ci: Changes to CI configuration files and "
-                            "scripts (example scopes: GitLabCI)"
+                            "scripts (example scopes: GitLabCI). "
+                            "No version bump (unless BREAKING CHANGE)"
                         ),
                         "key": "c",
                     },

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.
 

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)

docs/external_links.md

@@ -16,4 +16,22 @@
 - [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/)
+- [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