Skip to content

Commit 1242932

Browse files
bearomorphismCopilot
bearomorphism
and
Copilot
committed
fix(conventional_commits): add missing version bump notes for all change types
Closes #515 * Update the cz commit prompt to state the version bump impact for every Conventional Commit type, matching the existing 'Correlates with X in SemVer' phrasing already used for fix and feat: - refactor, perf -> 'Correlates with PATCH in SemVer' - docs, style, test, build, ci -> 'Correlates with no version bump in SemVer' * 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, PEP 440) and cross-link it from docs/commands/bump.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 4d99415 commit 1242932

4 files changed

Lines changed: 52 additions & 10 deletions

File tree

‎commitizen/cz/conventional_commits/conventional_commits.py‎

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -62,49 +62,62 @@ def questions(self) -> list[CzQuestion]:
6262
},
6363
{
6464
"value": "docs",
65-
"name": "docs: Documentation only changes",
65+
"name": (
66+
"docs: Documentation only changes. "
67+
"Correlates with no version bump in SemVer"
68+
),
6669
"key": "d",
6770
},
6871
{
6972
"value": "style",
7073
"name": (
7174
"style: Changes that do not affect the "
7275
"meaning of the code (white-space, formatting,"
73-
" missing semi-colons, etc)"
76+
" missing semi-colons, etc). "
77+
"Correlates with no version bump in SemVer"
7478
),
7579
"key": "s",
7680
},
7781
{
7882
"value": "refactor",
7983
"name": (
8084
"refactor: A code change that neither fixes "
81-
"a bug nor adds a feature"
85+
"a bug nor adds a feature. "
86+
"Correlates with PATCH in SemVer"
8287
),
8388
"key": "r",
8489
},
8590
{
8691
"value": "perf",
87-
"name": "perf: A code change that improves performance",
92+
"name": (
93+
"perf: A code change that improves performance. "
94+
"Correlates with PATCH in SemVer"
95+
),
8896
"key": "p",
8997
},
9098
{
9199
"value": "test",
92-
"name": ("test: Adding missing or correcting existing tests"),
100+
"name": (
101+
"test: Adding missing or correcting existing tests. "
102+
"Correlates with no version bump in SemVer"
103+
),
93104
"key": "t",
94105
},
95106
{
96107
"value": "build",
97108
"name": (
98109
"build: Changes that affect the build system or "
99-
"external dependencies (example scopes: pip, docker, npm)"
110+
"external dependencies (example scopes: pip, docker, npm). "
111+
"Correlates with no version bump in SemVer"
100112
),
101113
"key": "b",
102114
},
103115
{
104116
"value": "ci",
105117
"name": (
106118
"ci: Changes to CI configuration files and "
107-
"scripts (example scopes: GitLabCI)"
119+
"scripts (example scopes: GitLabCI). "
120+
"Correlates with no version bump in SemVer"
108121
),
109122
"key": "c",
110123
},

‎commitizen/cz/conventional_commits/conventional_commits_info.txt‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,17 @@ A BREAKING CHANGE can be part of commits of any type.
1515
Others: commit types other than fix: and feat: are allowed,
1616
like chore:, docs:, style:, refactor:, perf:, test:, and others.
1717

18-
We also recommend improvement for commits that improve a current
19-
implementation without adding a new feature or fixing a bug.
20-
2118
Notice these types are not mandated by the conventional commits specification,
2219
and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE).
2320

21+
Commitizen extends this set with sensible defaults: by default, refactor: and perf:
22+
correlate with PATCH in semantic versioning, while docs:, style:, test:, build:, ci:,
23+
and other types do not bump the version (unless they include a BREAKING CHANGE).
24+
These defaults can be customized via the `bump_map` and `bump_pattern` settings.
25+
26+
We also recommend improvement for commits that improve a current
27+
implementation without adding a new feature or fixing a bug.
28+
2429
A scope may be provided to a commit’s type, to provide additional contextual
2530
information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays.
2631

‎docs/commands/bump.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,11 @@ The version follows the `MAJOR.MINOR.PATCH` format, with increments determined b
3030
| `MINOR` | New features | `feat` |
3131
| `PATCH` | Fixes and improvements | `fix`, `perf`, `refactor`|
3232

33+
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.
34+
35+
!!! tip "Recommended reading on versioning"
36+
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).
37+
3338
## Command line options
3439

3540
![cz bump --help](../images/cli_help/cz_bump___help.svg)

‎docs/external_links.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,23 @@
1616
- [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)
1717
- [Continuous delivery made easy (in Python)](https://blog.devgenius.io/continuous-delivery-made-easy-in-python-c085e9c82e69)
1818

19+
## Recommended Reading on Versioning
20+
21+
The following articles, surfaced in the discussion of [issue #515][issue-515],
22+
provide useful background on the strengths and limitations of semantic
23+
versioning and on alternative versioning strategies. They can help calibrate
24+
expectations about what a version bump can — and cannot — guarantee to
25+
downstream consumers.
26+
27+
- [Semantic Versioning Will Not Save You](https://hynek.me/articles/semver-will-not-save-you/) by Hynek Schlawack
28+
- [Why I don't like SemVer anymore](https://snarky.ca/why-i-dont-like-semver/) by Brett Cannon
29+
- [Versioning Software](https://caremad.io/posts/2016/02/versioning-software/) by Donald Stufft
30+
- [Hyrum's Law](https://www.hyrumslaw.com/) — on implicit behavioral contracts beyond the documented API
31+
- [0ver — Zero-based Versioning](https://0ver.org/)
32+
- [CalVer — Calendar Versioning](https://calver.org/)
33+
- [PEP 440 — Version Identification and Dependency Specification](https://peps.python.org/pep-0440/)
34+
- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
35+
- [Semantic Versioning 2.0.0](https://semver.org/)
36+
1937
[automatizando]: https://youtu.be/t3aE2M8UPBo
38+
[issue-515]: https://github.com/commitizen-tools/commitizen/issues/515

0 commit comments

Comments
 (0)