From 64c017a332d47308bb9feced4134cae277ebccd1 Mon Sep 17 00:00:00 2001 From: Daniel Bates Date: Thu, 19 Feb 2026 20:08:34 -0800 Subject: [PATCH] docs: add version bump annotations to all commit type descriptions Add SemVer version bump information to all commit type descriptions in the interactive prompt, info text, and writing commits documentation. Previously, only `feat` and `fix` indicated their SemVer correlation. Now `refactor` and `perf` explicitly state they correlate with PATCH, and `docs`, `style`, `test`, `build`, and `ci` explicitly state they do not trigger a version bump. This addresses the remaining task from issue #515 which requested that commit message instructions identify what version bump occurs with all change types. Closes #515 Co-Authored-By: Claude Opus 4.6 --- .../conventional_commits.py | 15 +++++++------ .../conventional_commits_info.txt | 14 +++++++++--- docs/tutorials/writing_commits.md | 22 +++++++++---------- 3 files changed, 30 insertions(+), 21 deletions(-) diff --git a/commitizen/cz/conventional_commits/conventional_commits.py b/commitizen/cz/conventional_commits/conventional_commits.py index 31c329595a..0a6baf9a36 100644 --- a/commitizen/cz/conventional_commits/conventional_commits.py +++ b/commitizen/cz/conventional_commits/conventional_commits.py @@ -62,7 +62,7 @@ def questions(self) -> list[CzQuestion]: }, { "value": "docs", - "name": "docs: Documentation only changes", + "name": "docs: Documentation only changes. No version bump", "key": "d", }, { @@ -70,7 +70,7 @@ 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). No version bump" ), "key": "s", }, @@ -78,25 +78,26 @@ 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. No version bump"), "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" ), "key": "b", }, @@ -104,7 +105,7 @@ def questions(self) -> list[CzQuestion]: "value": "ci", "name": ( "ci: Changes to CI configuration files and " - "scripts (example scopes: GitLabCI)" + "scripts (example scopes: GitLabCI). No version bump" ), "key": "c", }, diff --git a/commitizen/cz/conventional_commits/conventional_commits_info.txt b/commitizen/cz/conventional_commits/conventional_commits_info.txt index a076e4f5ec..0df9b5051f 100644 --- a/commitizen/cz/conventional_commits/conventional_commits_info.txt +++ b/commitizen/cz/conventional_commits/conventional_commits_info.txt @@ -7,13 +7,21 @@ fix: a commit of the type fix patches a bug in your codebase feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in semantic versioning). +refactor: a commit of the type refactor is a code change that neither +fixes a bug nor adds a feature +(this correlates with PATCH in semantic versioning). + +perf: a commit of the type perf is a code change that improves performance +(this correlates with PATCH in semantic versioning). + BREAKING CHANGE: a commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with MAJOR in semantic versioning). 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. +Others: commit types other than fix:, feat:, refactor:, and perf: are allowed, +like chore:, docs:, style:, test:, build:, ci:, and others. +These types do not trigger a version bump by default. We also recommend improvement for commits that improve a current implementation without adding a new feature or fixing a bug. @@ -21,7 +29,7 @@ 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). -A scope may be provided to a commit’s type, to provide additional contextual +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. [optional scope]: diff --git a/docs/tutorials/writing_commits.md b/docs/tutorials/writing_commits.md index b8aa7f30f0..f04ad2462b 100644 --- a/docs/tutorials/writing_commits.md +++ b/docs/tutorials/writing_commits.md @@ -20,24 +20,24 @@ The Conventional Commits specification follows this structure: ### Commit Types -Commit types categorize the nature of your changes. The most important types for semantic versioning are: +Commit types categorize the nature of your changes. By default, Commitizen uses the [Angular Convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) commit types. The following types affect semantic versioning: - **`feat`**: Introduces a new feature (correlates with **MINOR** version increment) - **`fix`**: Patches a bug (correlates with **PATCH** version increment) +- **`refactor`**: A code change that neither fixes a bug nor adds a feature (correlates with **PATCH** version increment) +- **`perf`**: A code change that improves performance (correlates with **PATCH** version increment) -Other commonly used types include: +The following types do **not** trigger a version bump by default: -- **`docs`**: Documentation only changes -- **`style`**: Code style changes (formatting, missing semicolons, etc.) -- **`refactor`**: Code refactoring without changing functionality -- **`perf`**: Performance improvements -- **`test`**: Adding or updating tests -- **`build`**: Changes to build system or dependencies -- **`ci`**: Changes to CI configuration files -- **`chore`**: Other changes that don't modify source or test files +- **`docs`**: Documentation only changes (no version bump) +- **`style`**: Code style changes such as formatting, missing semicolons, etc. (no version bump) +- **`test`**: Adding or updating tests (no version bump) +- **`build`**: Changes to build system or dependencies (no version bump) +- **`ci`**: Changes to CI configuration files (no version bump) +- **`chore`**: Other changes that don't modify source or test files (no version bump) !!! note - While `feat` and `fix` directly affect semantic versioning, other types (like `build`, `chore`, `docs`) typically don't trigger version bumps unless they include a `BREAKING CHANGE`. + Only `feat`, `fix`, `refactor`, and `perf` trigger version bumps by default. All other types (like `docs`, `style`, `test`, `build`, `ci`, `chore`) do not trigger version bumps unless they include a `BREAKING CHANGE`. You can customize this behavior through the [bump_map configuration](../customization/config_file.md). ### Breaking Changes