Skip to content

fix(conventional_commits): add missing version bump notes for all change types #1960

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bearomorphism wants to merge 1 commit into
base: master
Choose a base branch
from
+52 −10
Open

fix(conventional_commits): add missing version bump notes for all change types #1960

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 20 additions & 7 deletions commitizen/cz/conventional_commits/conventional_commits.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,49 +62,62 @@ 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",
},
{
"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). "
"Correlates with no version bump in SemVer"
),
"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. "
"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",
},
{
"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",
},
Expand Down
11 changes: 8 additions & 3 deletions commitizen/cz/conventional_commits/conventional_commits_info.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
5 changes: 5 additions & 0 deletions docs/commands/bump.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
19 changes: 19 additions & 0 deletions docs/external_links.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading