diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index e28480e5b9..e37148c0a1 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -25,6 +25,13 @@ Please fill in the following content to let us know better about this change.
### Documentation Changes
- [ ] Run `poetry doc` locally to ensure the documentation pages renders correctly
+- [ ] Check and fix any broken links (internal or external) in the documentation
+
+> When running `poetry doc`, any broken internal documentation links will be reported in the console output like this:
+>
+> ```text
+> INFO - Doc file 'config.md' contains a link 'commands/bump.md#-post_bump_hooks', but the doc 'commands/bump.md' does not contain an anchor '#-post_bump_hooks'.
+> ```
## Expected Behavior
diff --git a/.github/workflows/label_pr.yml b/.github/workflows/label_pr.yml
index b409c8b757..176d7cc794 100644
--- a/.github/workflows/label_pr.yml
+++ b/.github/workflows/label_pr.yml
@@ -17,3 +17,31 @@ jobs:
- uses: actions/labeler@v5
with:
configuration-path: .github/labeler.yml
+ - name: Label based on PR title
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const title = context.payload.pull_request.title.toLowerCase();
+ const labels = [];
+
+ if (title.includes("fix") || title.includes("bug")) {
+ labels.push("type: bug");
+ }
+ if (title.includes("feat")) {
+ labels.push("type: feature");
+ }
+ if (title.includes("doc")) {
+ labels.push("type: documentation");
+ }
+ if (title.includes("refactor")) {
+ labels.push("type: refactor");
+ }
+
+ if (labels.length > 0) {
+ await github.rest.issues.addLabels({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: context.payload.pull_request.number,
+ labels
+ });
+ }
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f1aef91193..4e108eb9b9 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -48,7 +48,7 @@ repos:
- tomli
- repo: https://github.com/commitizen-tools/commitizen
- rev: v4.8.1 # automatically updated by Commitizen
+ rev: v4.8.2 # automatically updated by Commitizen
hooks:
- id: commitizen
- id: commitizen-branch
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9904ae3bbf..5b737a851a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,10 @@
+## v4.8.2 (2025-05-22)
+
+### Refactor
+
+- **check**: simplify code
+- **check**: remove unnecessary variable
+
## v4.8.1 (2025-05-22)
### Refactor
diff --git a/commitizen/__version__.py b/commitizen/__version__.py
index 1969a66ecd..8e288a597c 100644
--- a/commitizen/__version__.py
+++ b/commitizen/__version__.py
@@ -1 +1 @@
-__version__ = "4.8.1"
+__version__ = "4.8.2"
diff --git a/commitizen/cli.py b/commitizen/cli.py
index d08afc6706..cb834c5d6f 100644
--- a/commitizen/cli.py
+++ b/commitizen/cli.py
@@ -86,9 +86,8 @@ def __call__(
data = {
"prog": "cz",
"description": (
- "Commitizen is a cli tool to generate conventional commits.\n"
- "For more information about the topic go to "
- "https://conventionalcommits.org/"
+ "Commitizen is a powerful release management tool that helps teams maintain consistent and meaningful commit messages while automating version management.\n"
+ "For more information, please visit https://commitizen-tools.github.io/commitizen"
),
"formatter_class": argparse.RawDescriptionHelpFormatter,
"arguments": [
@@ -105,7 +104,7 @@ def __call__(
"name": ["-nr", "--no-raise"],
"type": str,
"required": False,
- "help": "comma separated error codes that won't rise error, e.g: cz -nr 1,2,3 bump. See codes at https://commitizen-tools.github.io/commitizen/exit_codes/",
+ "help": "comma separated error codes that won't raise error, e.g: cz -nr 1,2,3 bump. See codes at https://commitizen-tools.github.io/commitizen/exit_codes/",
},
],
"subcommands": {
diff --git a/commitizen/commands/check.py b/commitizen/commands/check.py
index 087db03ea5..1e3b8464e1 100644
--- a/commitizen/commands/check.py
+++ b/commitizen/commands/check.py
@@ -72,15 +72,11 @@ def __call__(self):
raise NoCommitsFoundError(f"No commit found with range: '{self.rev_range}'")
pattern = self.cz.schema_pattern()
- ill_formatted_commits = [
- commit
- for commit in commits
- if not self.validate_commit_message(commit.message, pattern)
- ]
displayed_msgs_content = "\n".join(
[
f'commit "{commit.rev}": "{commit.message}"'
- for commit in ill_formatted_commits
+ for commit in commits
+ if not self.validate_commit_message(commit.message, pattern)
]
)
if displayed_msgs_content:
@@ -92,24 +88,21 @@ def __call__(self):
)
out.success("Commit validation: successful!")
+ def _get_commit_message(self) -> str | None:
+ if self.commit_msg_file is None:
+ # Get commit message from command line (--message)
+ return self.commit_msg
+
+ with open(self.commit_msg_file, encoding=self.encoding) as commit_file:
+ # Get commit message from file (--commit-msg-file)
+ return commit_file.read()
+
def _get_commits(self):
- msg = None
- # Get commit message from file (--commit-msg-file)
- if self.commit_msg_file is not None:
- # Enter this branch if commit_msg_file is "".
- with open(self.commit_msg_file, encoding=self.encoding) as commit_file:
- msg = commit_file.read()
- # Get commit message from command line (--message)
- elif self.commit_msg is not None:
- msg = self.commit_msg
- if msg is not None:
- msg = self._filter_comments(msg)
- return [git.GitCommit(rev="", title="", body=msg)]
+ if (msg := self._get_commit_message()) is not None:
+ return [git.GitCommit(rev="", title="", body=self._filter_comments(msg))]
# Get commit messages from git log (--rev-range)
- if self.rev_range:
- return git.get_commits(end=self.rev_range)
- return git.get_commits()
+ return git.get_commits(end=self.rev_range or "HEAD")
@staticmethod
def _filter_comments(msg: str) -> str:
diff --git a/docs/README.md b/docs/README.md
index 128602dfb3..31f2a77d15 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,168 +8,310 @@
[](https://codecov.io/gh/commitizen-tools/commitizen)
[](https://github.com/pre-commit/pre-commit)
-
+
---
-**Documentation:** [https://commitizen-tools.github.io/commitizen/](https://commitizen-tools.github.io/commitizen/)
+[**Commitizen Documentation Site**](https://commitizen-tools.github.io/commitizen/)
---
## About
-Commitizen is release management tool designed for teams.
+Commitizen is a powerful release management tool that helps teams maintain consistent and meaningful commit messages while automating version management.
-Commitizen assumes your team uses a standard way of committing rules
-and from that foundation, it can bump your project's version, create
-the changelog, and update files.
+### What Commitizen Does
-By default, commitizen uses [conventional commits][conventional_commits], but you
-can build your own set of rules, and publish them.
+By enforcing standardized commit conventions (defaulting to [Conventional Commits][conventional_commits]), Commitizen helps teams:
-Using a standardized set of rules to write commits, makes commits easier to read, and enforces writing
-descriptive commits.
+- Write clear, structured commit messages
+- Automatically manage version numbers using semantic versioning
+- Generate and maintain changelogs
+- Streamline the release process
+
+### Key Benefits
+
+With just a simple `cz bump` command, Commitizen handles:
+
+1. **Version Management**: Automatically bumps version numbers and updates version files based on your commit history
+2. **Changelog Generation**: Creates and updates changelogs following the [Keep a changelog][keepchangelog] format
+3. **Commit Standardization**: Enforces consistent commit message formats across your team
+
+This standardization makes your commit history more readable and meaningful, while the automation reduces manual work and potential errors in the release process.
### Features
-- Command-line utility to create commits with your rules. Defaults: [Conventional commits][conventional_commits]
-- Bump version automatically using [semantic versioning][semver] based on the commits. [Read More](./commands/bump.md)
-- Generate a changelog using [Keep a changelog][keepchangelog]
-- Update your project's version files automatically
-- Display information about your commit rules (commands: schema, example, info)
-- Create your own set of rules and publish them to pip. Read more on [Customization](./customization.md)
+- Interactive CLI for standardized commits with default [Conventional Commits][conventional_commits] support
+- Intelligent [version bumping](https://commitizen-tools.github.io/commitizen/commands/bump/) using [Semantic Versioning][semver]
+- Automatic [keep a changelog][keepchangelog] generation
+- Built-in commit validation with pre-commit hooks
+- [Customizable](https://commitizen-tools.github.io/commitizen/customization/) commit rules and templates
+- Multi-format version file support
+- Custom rules and plugins via pip
+
+## Getting Started
-## Requirements
+### Requirements
-[Python](https://www.python.org/downloads/) `3.9+`
+Before installing Commitizen, ensure you have:
-[Git][gitscm] `1.8.5.2+`
+- [Python](https://www.python.org/downloads/) `3.9+`
+- [Git][gitscm] `1.8.5.2+`
-## Installation
+### Installation
-Install commitizen in your system using `pipx` (Recommended, ):
+#### Global Installation (Recommended)
+The recommended way to install Commitizen is using [`pipx`](https://pipx.pypa.io/) or [`uv`](https://docs.astral.sh/uv/), which ensures a clean, isolated installation:
+**Using pipx:**
```bash
-pipx ensurepath
+# Install Commitizen
pipx install commitizen
+
+# Keep it updated
pipx upgrade commitizen
```
-Install commitizen using `pip` with `--user` flag:
-
+**Using uv:**
```bash
-pip install --user -U commitizen
+# Install commitizen
+uv tool install commitizen
+
+# Keep it updated
+uv tool upgrade commitizen
```
-### Python project
+**(For macOS users) Using Homebrew:**
+```bash
+brew install commitizen
+```
-You can add it to your local project using one of the following.
+#### Project-Specific Installation
-With `pip`:
+You can add Commitizen to your Python project using any of these package managers:
+**Using pip:**
```bash
pip install -U commitizen
```
-With `conda`:
-
+**Using conda:**
```bash
conda install -c conda-forge commitizen
```
-With Poetry >= 1.2.0:
-
+**Using Poetry:**
```bash
+# For Poetry >= 1.2.0
poetry add commitizen --group dev
+
+# For Poetry < 1.2.0
+poetry add commitizen --dev
```
-With Poetry < 1.2.0:
+**Using uv:**
+```bash
+uv add commitizen
+```
+**Using pdm:**
```bash
-poetry add commitizen --dev
+pdm add -d commitizen
```
-### macOS
+### Basic Commands
-via [homebrew](https://formulae.brew.sh/formula/commitizen):
+#### Initialize Commitizen
-```bash
-brew install commitizen
+To get started, you'll need to set up your configuration. You have two options:
+
+1. Use the interactive setup:
+```sh
+cz init
```
-## Usage
+2. Manually create a configuration file (`.cz.toml` or `cz.toml`):
+```toml
+[tool.commitizen]
+version = "0.1.0"
+update_changelog_on_bump = true
+```
-Most of the time this is the only command you'll run:
+#### Create Commits
+
+Create standardized commits using:
+```sh
+cz commit
+# or use the shortcut
+cz c
+```
+To sign off your commits:
+```sh
+cz commit -- --signoff
+# or use the shortcut
+cz commit -- -s
+```
+
+For more commit options, run `cz commit --help`.
+
+#### Version Management
+
+The most common command you'll use is:
```sh
cz bump
```
-On top of that, you can use commitizen to assist you with the creation of commits:
+This command:
+
+- Bumps your project's version
+- Creates a git tag
+- Updates the changelog (if `update_changelog_on_bump` is enabled)
+- Updates version files
+
+You can customize:
+
+- [Version files](https://commitizen-tools.github.io/commitizen/commands/bump/#version_files)
+- [Version scheme](https://commitizen-tools.github.io/commitizen/commands/bump/#version_scheme)
+- [Version provider](https://commitizen-tools.github.io/commitizen/config/#version-providers)
+
+For all available options, see the [bump command documentation](https://commitizen-tools.github.io/commitizen/commands/bump/).
+
+### Advanced Usage
+
+#### Get Project Version
```sh
-cz commit
+# Get your project's version (instead of Commitizen's version)
+cz version -p
+# Preview changelog changes
+cz changelog --dry-run "$(cz version -p)"
```
-Read more in the section [Getting Started](./getting_started.md).
+This command is particularly useful for automation scripts and CI/CD pipelines.
+
+For example, you can use the output of the command `cz changelog --dry-run "$(cz version -p)"` to notify your team about a new release in Slack.
+
+#### Pre-commit Integration
+
+Commitizen can automatically validate your commit messages using pre-commit hooks.
+
+1. Add to your `.pre-commit-config.yaml`:
+```yaml
+---
+repos:
+ - repo: https://github.com/commitizen-tools/commitizen
+ rev: master # Replace with latest tag
+ hooks:
+ - id: commitizen
+ - id: commitizen-branch
+ stages: [pre-push]
+```
+
+2. Install the hooks:
+```sh
+pre-commit install --hook-type commit-msg --hook-type pre-push
+```
+
+| Hook | Recommended Stage |
+| ----------------- | ----------------- |
+| commitizen | commit-msg |
+| commitizen-branch | pre-push |
+
+> **Note**: Replace `master` with the [latest tag](https://github.com/commitizen-tools/commitizen/tags) to avoid warnings. You can automatically update this with:
+> ```sh
+> pre-commit autoupdate
+> ```
+
+For more details about commit validation, see the [check command documentation](https://commitizen-tools.github.io/commitizen/commands/check/).
+
+## Help & Reference
-### Help
+### Command Line Interface
+
+Commitizen provides a comprehensive CLI with various commands. Here's the complete reference:
+
+
+
+### Quick Reference
+
+| Command | Description | Alias |
+|---------|-------------|-------|
+| `cz init` | Initialize Commitizen configuration | - |
+| `cz commit` | Create a new commit | `cz c` |
+| `cz bump` | Bump version and update changelog | - |
+| `cz changelog` | Generate changelog | `cz ch` |
+| `cz check` | Validate commit messages | - |
+| `cz version` | Show version information | - |
+
+### Additional Resources
+
+- [Conventional Commits Specification][conventional_commits]
+- [Exit Codes Reference](https://commitizen-tools.github.io/commitizen/exit_codes/)
+- [Configuration Guide](https://commitizen-tools.github.io/commitizen/config/)
+- [Command Documentation](https://commitizen-tools.github.io/commitizen/commands/init/)
+
+### Getting Help
+
+For each command, you can get detailed help by adding `--help`:
```sh
-$ cz --help
-usage: cz [-h] [--debug] [-n NAME] [-nr NO_RAISE] {init,commit,c,ls,example,info,schema,bump,changelog,ch,check,version} ...
-
-Commitizen is a cli tool to generate conventional commits.
-For more information about the topic go to https://conventionalcommits.org/
-
-optional arguments:
- -h, --help show this help message and exit
- --config the path of configuration file
- --debug use debug mode
- -n NAME, --name NAME use the given commitizen (default: cz_conventional_commits)
- -nr NO_RAISE, --no-raise NO_RAISE
- comma separated error codes that won't rise error, e.g: cz -nr 1,2,3 bump. See codes at https://commitizen-
- tools.github.io/commitizen/exit_codes/
-
-commands:
- {init,commit,c,ls,example,info,schema,bump,changelog,ch,check,version}
- init init commitizen configuration
- commit (c) create new commit
- ls show available commitizens
- example show commit example
- info show information about the cz
- schema show commit schema
- bump bump semantic version based on the git log
- changelog (ch) generate changelog (note that it will overwrite existing file)
- check validates that a commit message matches the commitizen schema
- version get the version of the installed commitizen or the current project (default: installed commitizen)
+cz commit --help
+cz bump --help
+cz changelog --help
```
+For more details, visit our [documentation site](https://commitizen-tools.github.io/commitizen/).
+
## Setting up bash completion
-When using bash as your shell (limited support for zsh, fish, and tcsh is available), Commitizen can use [argcomplete](https://kislyuk.github.io/argcomplete/) for auto-completion. For this argcomplete needs to be enabled.
+Commitizen supports command-line completion through [argcomplete](https://kislyuk.github.io/argcomplete/), which is automatically installed as a dependency. This feature provides intelligent auto-completion for all Commitizen commands and options.
-argcomplete is installed when you install Commitizen since it's a dependency.
+### Supported Shells
-If Commitizen is installed globally, global activation can be executed:
+- **Bash**: Full support
+- **Zsh**: Limited support
+- **Fish**: Limited support
+- **Tcsh**: Limited support
+
+### Installation Methods
+
+#### Global Installation (Recommended)
+
+If you installed Commitizen globally (e.g., using `pipx` or `brew`), you can enable global completion:
```bash
+# Enable global completion for all Python applications
sudo activate-global-python-argcomplete
```
-For permanent (but not global) Commitizen activation, use:
+#### User-Specific Installation
+
+For a user-specific installation that persists across sessions:
```bash
+# Add to your shell's startup file (e.g., ~/.bashrc, ~/.zshrc)
register-python-argcomplete cz >> ~/.bashrc
```
-For one-time activation of argcomplete for Commitizen only, use:
+#### Temporary Installation
+
+For one-time activation in your current shell session:
```bash
+# Activate completion for current session only
eval "$(register-python-argcomplete cz)"
```
-For further information on activation, please visit the [argcomplete website](https://kislyuk.github.io/argcomplete/).
+### Verification
+
+After installation, you can verify the completion is working by:
+
+1. Opening a new terminal session
+2. Typing `cz` followed by a space and pressing `TAB` twice
+3. You should see a list of available commands
+
+For more detailed information about argcomplete configuration and troubleshooting, visit the [argcomplete documentation](https://kislyuk.github.io/argcomplete/).
## Sponsors
diff --git a/docs/commands/bump.md b/docs/commands/bump.md
index efdba76257..8219cc3461 100644
--- a/docs/commands/bump.md
+++ b/docs/commands/bump.md
@@ -2,51 +2,79 @@
## About
-`cz bump` **automatically** increases the version, based on the commits.
+`cz bump` is a powerful command that **automatically** determines and increases your project's version number based on your commit history. It analyzes your commits to determine the appropriate version increment according to semantic versioning principles.
-The commits should follow the rules established by the committer in order to be parsed correctly.
+### Key Features
-**prerelease** versions are supported (alpha, beta, release candidate).
+- **Automatic Version Detection**: Analyzes commit history to determine the appropriate version bump
+- **Manual Version Control**: Supports manual version specification when needed
+- **Pre-release Support**: Handles alpha, beta, and release candidate versions
+- **Multiple Version Schemes**: Supports both [PEP 0440][pep440] and [semantic versioning][semver] formats
-The version can also be **manually** bumped.
+### Version Increment Rules
-The version format follows [PEP 0440][pep440] and [semantic versioning][semver].
-
-This means `MAJOR.MINOR.PATCH`
+The version follows the `MAJOR.MINOR.PATCH` format, with increments determined by your commit types:
| Increment | Description | Conventional commit map |
| --------- | --------------------------- | ----------------------- |
-| `MAJOR` | Breaking changes introduced | `BREAKING CHANGE` |
+| `MAJOR` | Breaking changes introduced | `BREAKING CHANGE`, bang (e.g. `feat!`)|
| `MINOR` | New features | `feat` |
-| `PATCH` | Fixes | `fix` + everything else |
+| `PATCH` | Fixes and improvements | `fix`, `perf`, `refactor`|
+
+### Version Schemes
-[PEP 0440][pep440] is the default, you can switch by using the setting `version_scheme` or the cli:
+By default, Commitizen uses [PEP 0440][pep440] for version formatting. You can switch to semantic versioning using either:
+1. Command line:
```sh
cz bump --version-scheme semver
```
-Some examples of pep440:
+2. Configuration file:
+```toml
+[tool.commitizen]
+version_scheme = "semver"
+```
-```bash
-0.9.0
-0.9.1
-0.9.2
-0.9.10
-0.9.11
-1.0.0a0 # alpha
-1.0.0a1
-1.0.0b0 # beta
-1.0.0rc0 # release candidate
-1.0.0rc1
-1.0.0
-1.0.1
-1.1.0
-2.0.0
-2.0.1a
-```
-
-`post` releases are not supported yet.
+### PEP440 Version Examples
+
+Commitizen supports the [PEP 440][pep440] version format, which includes several version types. Here are examples of each:
+
+#### Standard Releases
+```text
+0.9.0 # Initial development release
+0.9.1 # Patch release
+0.9.2 # Another patch release
+0.9.10 # Tenth patch release
+0.9.11 # Eleventh patch release
+1.0.0 # First stable release
+1.0.1 # Patch release after stable
+1.1.0 # Minor feature release
+2.0.0 # Major version release
+```
+
+#### Pre-releases
+```text
+1.0.0a0 # Alpha release 0
+1.0.0a1 # Alpha release 1
+1.0.0b0 # Beta release 0
+1.0.0rc0 # Release candidate 0
+1.0.0rc1 # Release candidate 1
+```
+
+#### Development Releases
+```text
+1.0.0.dev0 # Development release 0
+1.0.0.dev1 # Development release 1
+```
+
+#### Combined Pre-release and Development
+```text
+1.0.0a1.dev0 # Development release 0 of alpha 1
+1.0.0b2.dev1 # Development release 1 of beta 2
+```
+
+> **Note**: `post` releases (e.g., `1.0.0.post1`) are not currently supported.
## Usage
@@ -72,7 +100,7 @@ cz bump --changelog
The bump is a pre-release bump, meaning that in addition to a possible version bump the new version receives a
pre-release segment compatible with the bump’s version scheme, where the segment consist of a _phase_ and a
-non-negative number. Supported options for `--prerelease` are the following phase names `alpha`, `beta`, or
+non-negative number. Supported options for `--prerelease` are the following phase names `alpha`, `beta`, or
`rc` (release candidate). For more details, refer to the
[Python Packaging User Guide](https://packaging.python.org/en/latest/specifications/version-specifiers/#pre-releases).
@@ -97,7 +125,7 @@ by their precedence and showcase how a release might flow through a development
By default, `--increment-mode` is set to `linear`, which ensures that bumping pre-releases _maintains linearity_:
bumping of a pre-release with lower precedence than the current pre-release phase maintains the current phase of
higher precedence. For example, if the current version is `1.0.0b1` then bumping with `--prerelease alpha` will
-continue to bump the “beta” phase.
+continue to bump the "beta" phase.
Setting `--increment-mode` to `exact` instructs `cz bump` to instead apply the
exact changes that have been specified with `--increment` or determined from the commit log. For example,
@@ -116,7 +144,7 @@ Below are some examples that illustrate the difference in behavior:
### `--check-consistency`
-Check whether the versions defined in `version_files` and the version in commitizen
+Check whether the versions defined in `version_files` and the version in Commitizen
configuration are consistent before bumping version.
```bash
@@ -148,7 +176,7 @@ from setuptools import setup
setup(..., version="1.0.5", ...)
```
-If `--check-consistency` is used, commitizen will check whether the current version in `pyproject.toml`
+If `--check-consistency` is used, Commitizen will check whether the current version in `pyproject.toml`
exists in all version_files and find out it does not exist in `setup.py` and fails.
However, it will still update `pyproject.toml` and `src/__version__.py`.
@@ -174,11 +202,11 @@ If `--local-version` is used, it will bump only the local version `0.1.0` and ke
### `--annotated-tag`
-If `--annotated-tag` is used, commitizen will create annotated tags. Also available via configuration, in `pyproject.toml` or `.cz.toml`.
+If `--annotated-tag` is used, Commitizen will create annotated tags. It is also available via configuration, in `pyproject.toml` or `.cz.toml`.
### `--annotated-tag-message`
-If `--annotated-tag-message` is used, commitizen will create annotated tags with the given message.
+If `--annotated-tag-message` is used, Commitizen will create annotated tags with the given message.
### `--changelog-to-stdout`
@@ -191,7 +219,7 @@ understand that the user wants to create a changelog. It is recommended to be
explicit and use `--changelog` (or the setting `update_changelog_on_bump`).
This command is useful to "transport" the newly created changelog.
-It can be sent to an auditing system, or to create a Github Release.
+It can be sent to an auditing system, or to create a GitHub Release.
Example:
@@ -223,7 +251,7 @@ If used together with a manual version the command also fails.
We recommend setting `major_version_zero = true` in your configuration file while a project
is in its initial development. Remove that configuration using a breaking-change commit to bump
-your project’s major version to `v1.0.0` once your project has reached maturity.
+your project's major version to `v1.0.0` once your project has reached maturity.
### `--version-scheme`
@@ -332,11 +360,11 @@ cz bump --allow-no-commit 2.0.0
## Avoid raising errors
-Some situations from commitizen raise an exit code different than 0.
-If the error code is different than 0, any CI or script running commitizen might be interrupted.
+Some situations from Commitizen raise an exit code different from 0.
+If the error code is different from 0, any CI or script running Commitizen might be interrupted.
If you have a special use case, where you don't want to raise one of this error codes, you can
-tell commitizen to not raise them.
+tell Commitizen to not raise them.
### Recommended use case
@@ -355,7 +383,7 @@ cz -nr 21 bump
### Easy way
-Check which error code was raised by commitizen by running in the terminal
+Check which error code was raised by Commitizen by running in the terminal
```sh
echo $?
@@ -367,13 +395,13 @@ The output should be an integer like this
3
```
-And then you can tell commitizen to ignore it:
+And then you can tell Commitizen to ignore it:
```sh
cz --no-raise 3
```
-You can tell commitizen to skip more than one if needed:
+You can tell Commitizen to skip more than one if needed:
```sh
cz --no-raise 3,4,5
@@ -387,7 +415,7 @@ to skip and why.
Remember to document somewhere this, because you'll forget.
For example if the system raises a `NoneIncrementExit` error, you look it up
-on the list and then you can use the exit code:
+on the list, and then you can use the exit code:
```sh
cz -nr 21 bump
@@ -403,7 +431,7 @@ These are used in:
- `cz bump`: Find previous release tag (exact match) and generate new tag.
- Find previous release tags in `cz changelog`.
- - If `--incremental`: Using latest version found in the changelog, scan existing Git tags with 89\% similarity match.
+ - If `--incremental`: Using the latest version found in the changelog, scan existing Git tags with 89\% similarity match.
- `--rev-range` is converted to Git tag names with `tag_format` before searching Git history.
- If the `scm` `version_provider` is used, it uses different regexes to find the previous version tags:
- If `tag_format` is set to `$version` (default): `VersionProtocol.parser` (allows `v` prefix)
@@ -477,7 +505,7 @@ in a line containing the `version` substring.
Template used to specify the commit message generated when bumping.
-defaults to: `bump: version $current_version → $new_version`
+Defaults to: `bump: version $current_version → $new_version`
| Variable | Description |
| ------------------ | ----------------------------------- |
@@ -499,7 +527,7 @@ bump_message = "release $current_version → $new_version [skip-ci]"
When set to `true` the changelog is always updated incrementally when running `cz bump`, so the user does not have to provide the `--changelog` flag every time.
-defaults to: `false`
+Defaults to: `false`
```toml
[tool.commitizen]
@@ -510,7 +538,7 @@ update_changelog_on_bump = true
### `annotated_tag`
-When set to `true` commitizen will create annotated tags.
+When set to `true`, Commitizen will create annotated tags.
```toml
[tool.commitizen]
@@ -521,7 +549,7 @@ annotated_tag = true
### `gpg_sign`
-When set to `true` commitizen will create gpg signed tags.
+When set to `true`, Commitizen will create gpg signed tags.
```toml
[tool.commitizen]
@@ -532,7 +560,7 @@ gpg_sign = true
### `major_version_zero`
-When set to `true` commitizen will keep the major version at zero.
+When set to `true`, Commitizen will keep the major version at zero.
Useful during the initial development stage of your project.
Defaults to: `false`
diff --git a/docs/commands/changelog.md b/docs/commands/changelog.md
index cbf22b15a7..aee1a0e075 100644
--- a/docs/commands/changelog.md
+++ b/docs/commands/changelog.md
@@ -56,7 +56,7 @@ These are the variables used by the changelog generator.
It will create a full block like above per version found in the tags.
And it will create a list of the commits found.
The `change_type` and the `scope` are optional, they don't need to be provided,
-but if your regex does they will be rendered.
+but if your regex does, they will be rendered.
The format followed by the changelog is the one from [keep a changelog][keepachangelog]
and the following variables are expected:
@@ -108,7 +108,7 @@ cz bump --changelog
This value can be updated in the `toml` file with the key `changelog_file` under `tools.commitizen`
-Specify the name of the output file, remember that changelog only works with markdown.
+Specify the name of the output file, remember that changelog only works with Markdown.
```bash
cz changelog --file-name="CHANGES.md"
@@ -120,7 +120,7 @@ This flag can be set in the `toml` file with the key `changelog_incremental` und
Benefits:
-- Build from latest version found in changelog, this is useful if you have a different changelog and want to use commitizen
+- Build from the latest version found in changelog, this is useful if you have a different changelog and want to use commitizen
- Update unreleased area
- Allows users to manually touch the changelog without being rewritten.
@@ -185,8 +185,8 @@ See [the template customization section](../customization.md#customizing-the-cha
Supported hook methods:
-- per parsed message: useful to add links
-- end of changelog generation: useful to send slack or chat message, or notify another department
+- Per parsed message: Useful to add links
+- End of changelog generation: Useful to send Slack or chat messages, or notify another department
Read more about hooks in the [customization page][customization]
diff --git a/docs/commands/check.md b/docs/commands/check.md
index e45ecd86c8..33e41e04f8 100644
--- a/docs/commands/check.md
+++ b/docs/commands/check.md
@@ -2,9 +2,9 @@
## About
-This feature checks whether the commit message follows the given committing rules. And comment in git message will be ignored.
+This feature checks whether the commit message follows the given committing rules. Comments in git messages will be ignored.
-If you want to setup an automatic check before every git commit, please refer to
+If you want to set up an automatic check before every git commit, please refer to
[Automatically check message before commit](../tutorials/auto_check.md).
## Usage
@@ -27,7 +27,7 @@ $ cz check --rev-range REV_RANGE
For example, if you'd like to check all commits on a branch, you can use `--rev-range master..HEAD`. Or, if you'd like to check all commits starting from when you first implemented commit message linting, you can use `--rev-range ..HEAD`.
-For more info on how git commit ranges work, you can check the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_commit_ranges).
+For more information on how git commit ranges work, you can check the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_commit_ranges).
### Commit Message
@@ -47,7 +47,7 @@ In this option, MESSAGE is the commit message to be checked.
$ echo MESSAGE | cz check
```
-In this option, MESSAGE is piped to cz check and would be checked.
+In this option, MESSAGE is piped to cz check and will be checked.
### Commit Message File
@@ -55,8 +55,8 @@ In this option, MESSAGE is piped to cz check and would be checked.
$ cz check --commit-msg-file COMMIT_MSG_FILE
```
-In this option, COMMIT_MSG_FILE is the path of the temporal file that contains the commit message.
-This argument can be useful when cooperating with git hook, please check [Automatically check message before commit](../tutorials/auto_check.md) for more information about how to use this argument with git hook.
+In this option, COMMIT_MSG_FILE is the path of the temporary file that contains the commit message.
+This argument can be useful when cooperating with git hooks. Please check [Automatically check message before commit](../tutorials/auto_check.md) for more information about how to use this argument with git hooks.
### Allow Abort
@@ -69,8 +69,8 @@ permit them. Since `git commit` accepts an `--allow-empty-message` flag (primari
### Allowed Prefixes
-If the commit message starts by some specific prefixes, `cz check` returns `True` without checkign the regex.
-By default, the the following prefixes are allowed: `Merge`, `Revert`, `Pull request`, `fixup!` and `squash!`.
+If the commit message starts with some specific prefixes, `cz check` returns `True` without checking the regex.
+By default, the following prefixes are allowed: `Merge`, `Revert`, `Pull request`, `fixup!` and `squash!`.
```bash
cz check --message MESSAGE --allowed-prefixes 'Merge' 'Revert' 'Custom Prefix'
@@ -78,10 +78,10 @@ cz check --message MESSAGE --allowed-prefixes 'Merge' 'Revert' 'Custom Prefix'
### Commit message length limit
-The argument `-l` (or `--message-length-limmit`) followed by a positive number, can limit the length of commit messages.
+The argument `-l` (or `--message-length-limit`) followed by a positive number can limit the length of commit messages.
For example, `cz check --message MESSAGE -l 3` would fail the check, since `MESSAGE` is more than 3 characters long.
By default, the limit is set to 0, which means no limit on the length.
-**Note that the limit applies only to the first line of the message.***
+**Note that the limit applies only to the first line of the message.**
Specifically, for `ConventionalCommitsCz` the length only counts from the type of change to the subject,
-while the body, and the footer are not counted.
+while the body and the footer are not counted.
diff --git a/docs/commands/commit.md b/docs/commands/commit.md
index 7760a2b88e..5a073a2644 100644
--- a/docs/commands/commit.md
+++ b/docs/commands/commit.md
@@ -1,52 +1,65 @@
-
+## Usage
-## About
+
-In your terminal run `cz commit` or the shortcut `cz c` to generate a guided git commit.
+## Overview
-You can run `cz commit --write-message-to-file COMMIT_MSG_FILE` to additionally save the
-generated message to a file. This can be combined with the `--dry-run` flag to only
-write the message to a file and not modify files and create a commit. A possible use
-case for this is to [automatically prepare a commit message](../tutorials/auto_prepare_commit_message.md).
+
+The `commit` command provides an interactive way to create structured commits. Use either:
-!!! note
- To maintain platform compatibility, the `commit` command disable ANSI escaping in its output.
- In particular pre-commit hooks coloring will be deactivated as discussed in [commitizen-tools/commitizen#417](https://github.com/commitizen-tools/commitizen/issues/417).
+- `cz commit`
+- `cz c` (shortcut)
-## Usage
+By default, Commitizen uses conventional commits, but you can customize the commit rules to match your project's needs. See the [customization guide](../customization.md) for details.
-
+## Basic Usage
-### git options
+### Interactive Commit Creation
-`git` command options that are not implemented by commitizen can be use via the `--` syntax for the `commit` command.
-The syntax separates commitizen arguments from `git commit` arguments by a double dash. This is the resulting syntax:
+Simply run `cz commit` in your terminal to start the interactive commit creation process. The command will guide you through creating a properly formatted commit message according to your configured rules.
+
+### Writing Messages to File
+
+You can save the generated commit message to a file using:
+```sh
+cz commit --write-message-to-file COMMIT_MSG_FILE
+```
+
+This can be combined with `--dry-run` to only write the message without creating a commit. This is particularly useful for [automatically preparing commit messages](../tutorials/auto_prepare_commit_message.md).
+
+## Advanced Features
+
+### Git Command Options
+
+You can pass any git commit options using the `--` syntax:
```sh
cz commit --
-# e.g., cz commit --dry-run -- -a -S
+# Examples:
+cz c --dry-run -- -a -S # Stage all changes and sign the commit
+cz c -a -- -n # Stage all changes and skip the pre-commit and commit-msg hooks
```
-For example, using the `-S` option on `git commit` to sign a commit is now commitizen compatible: `cz c -- -S`
-!!! note
- Deprecation warning: A commit can be signed off using `cz commit --signoff` or the shortcut `cz commit -s`.
- This syntax is now deprecated in favor of the new `cz commit -- -s` syntax.
+!!! warning
+ The `--signoff` option (or `-s`) is now recommended being used with the new syntax: `cz commit -- -s`. The old syntax `cz commit --signoff` is deprecated.
### Retry
-You can use `cz commit --retry` to reuse the last commit message when the previous commit attempt failed.
-To automatically retry when running `cz commit`, you can set the `retry_after_failure`
-configuration option to `true`. Running `cz commit --no-retry` makes commitizen ignore `retry_after_failure`, forcing
-a new commit message to be prompted.
+- Use `cz commit --retry` to reuse the last commit message after a failed commit attempt
+- Set `retry_after_failure: true` in your configuration to automatically retry
+- Use `cz commit --no-retry` to force a new commit message prompt
+
+### Message Length Control
-### Commit message length limit
+Control the length of your commit messages using the `-l` or `--message-length-limit` option:
+```sh
+cz commit -l 72 # Limits message length to 72 characters
+```
+
+!!! note
+ The length limit only applies to the first line of the commit message. For conventional commits, this means the limit applies from the type of change through the subject. The body and footer are not counted.
-The argument `-l` (or `--message-length-limit`) followed by a positive number can limit the length of commit messages.
-An exception would be raised when the message length exceeds the limit.
-For example, `cz commit -l 72` will limit the length of commit messages to 72 characters.
-By default the limit is set to 0, which means no limit on the length.
+## Technical Notes
-**Note that the limit applies only to the first line of the message.**
-Specifically, for `ConventionalCommitsCz` the length only counts from the type of change to the subject,
-while the body and the footer are not counted.
+For platform compatibility, the `commit` command disables ANSI escaping in its output. This means pre-commit hooks coloring will be deactivated as discussed in [commitizen-tools/commitizen#417](https://github.com/commitizen-tools/commitizen/issues/417).
diff --git a/docs/commands/init.md b/docs/commands/init.md
index 01e1db6be8..4d92112d34 100644
--- a/docs/commands/init.md
+++ b/docs/commands/init.md
@@ -1,27 +1,66 @@
+The `cz init` command helps you set up Commitizen in your project by creating a configuration file with your preferred settings.
+
## Usage
-## Example
-
-To start using commitizen, the recommended approach is to run
+## Command
```sh
cz init
```
+## Interactive Configuration
+
+When you run `cz init`, Commitizen will guide you through an interactive setup process:
+
-This command will ask you for information about the project and will
-configure the selected file type (`pyproject.toml`, `.cz.toml`, etc.).
+## Configuration File
+
+The initialization process will create a configuration file in your project root.
+
+Choose the configuration file format based on your project type:
+
+- Use `pyproject.toml` for Python projects
+- Use `.cz.toml`, `.cz.yaml`, `.cz.json`, etc. for other projects.
+
+## Configuration Options
+
+During the initialization process, you'll be prompted to configure the following settings:
+
+1. **Convention Rules**: Select the commit message convention to follow (e.g., conventional commits)
+2. **Version Provider**: Choose how to manage versioning in your project. Commitizen supports multiple version management systems:
+ - `commitizen`: Uses Commitizen's built-in version management system
+ - `npm`: Manages version in `package.json` for Node.js projects
+ - `cargo`: Manages version in `Cargo.toml` for Rust projects
+ - `composer`: Manages version in `composer.json` for PHP projects
+ - `pep621`: Uses `pyproject.toml` with PEP 621 standard
+ - `poetry`: Uses `pyproject.toml` with Poetry configuration
+ - `uv`: Uses `pyproject.toml` and `uv.lock` for Python projects
+ - `scm`: Reads version directly from git tags without modifying files
+3. **Project Version**: The current version of your project will be detected automatically
+4. **Tag Format**: The format used for version tags in your repository
+5. **Version Type**: Choose between:
+ - `semver` or `semver2`: Semantic Versioning (MAJOR.MINOR.PATCH)
+ - `pep440`: Python Package Versioning
+6. **Changelog Generation**: Configure whether to automatically generate changelog during version bumps
+7. **Alpha Versioning**: Option to keep major version at 0 for alpha/beta software
+8. **Pre-commit Hooks**: Set up Git pre-commit hooks for automated commit message validation
+
+## Example
+
+```sh
+# Start the initialization process
+cz init
+
+# Follow the interactive prompts to configure your project
+```
+
+## Next Steps
-The `init` will help you with
+After initialization, you can:
-1. Choose a convention rules (`name`)
-2. Choosing a version provider (`commitizen` or for example `Cargo.toml`)
-3. Detecting your project's version
-4. Detecting the tag format used
-5. Choosing a version type (`semver` or `pep440`)
-6. Whether to create the changelog automatically or not during bump
-7. Whether you want to keep the major as zero while building alpha software.
-8. Whether to setup pre-commit hooks.
+1. Start using `cz commit` to create conventional commits
+2. Use `cz bump` to manage versioning
+3. Configure additional settings in your project's configuration file
diff --git a/docs/commands/version.md b/docs/commands/version.md
index 9a8176b45f..4d2e6a0323 100644
--- a/docs/commands/version.md
+++ b/docs/commands/version.md
@@ -1,4 +1,4 @@
-Get the version of the installed commitizen or the current project (default: installed commitizen)
+Get the version of the installed Commitizen or the current project (default: installed commitizen)
## Usage
diff --git a/docs/config.md b/docs/config.md
index a522312743..5ca2c5d788 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -59,7 +59,7 @@ Default: `[ ]`
Legacy git tag formats, useful for old projects that changed tag format.
Tags matching those formats will be recognized as version tags and be included in the changelog.
-Each entry use the the syntax as [`tag_format`](#tag_format). [Read more][tag_format]
+Each entry uses the syntax as [`tag_format`](#tag_format). [Read more][tag_format]
### `ignored_tag_formats`
@@ -68,7 +68,7 @@ Type: `list`
Default: `[ ]`
Tags matching those formats will be totally ignored and won't raise a warning.
-Each entry use the the syntax as [`tag_format`](#tag_format) with the addition of `*`
+Each entry uses the syntax as [`tag_format`](#tag_format) with the addition of `*`
that will match everything (non-greedy). [Read more][tag_format]
### `update_changelog_on_bump`
@@ -101,7 +101,7 @@ Type: `str`
Default: `None`
-Create custom commit message, useful to skip ci. [Read more][bump_message]
+Create custom commit message, useful to skip CI. [Read more][bump_message]
### `retry_after_failure`
@@ -117,7 +117,7 @@ Type: `bool`
Default: `false`
-Disallow empty commit messages, useful in ci. [Read more][allow_abort]
+Disallow empty commit messages, useful in CI. [Read more][allow_abort]
### `allowed_prefixes`
@@ -187,7 +187,7 @@ Type: `bool`
Default: `false`
-If enabled, commitizen will show keyboard shortcuts when selecting from a list. Define a `key` for each of your choices to set the key. [Read more][shortcuts]
+If enabled, Commitizen will show keyboard shortcuts when selecting from a list. Define a `key` for each of your choices to set the key. [Read more][shortcuts]
### `major_version_zero`
@@ -195,7 +195,7 @@ Type: `bool`
Default: `false`
-When true, breaking changes on a `0.x` will remain as a `0.x` version. On `false`, a breaking change will bump a `0.x` version to `1.0`. [major-version-zero]
+When true, breaking changes on a `0.x` will remain as a `0.x` version. On `false`, a breaking change will bump a `0.x` version to `1.0`. [Read more][major-version-zero]
### `prerelease_offset`
@@ -203,7 +203,7 @@ Type: `int`
Default: `0`
-In some circumstances, a prerelease cannot start with a 0, e.g. in an embedded project individual characters are encoded as bytes. This can be done by specifying an offset from which to start counting. [prerelease-offset]
+In some circumstances, a prerelease cannot start with a 0, e.g. in an embedded project individual characters are encoded as bytes. This can be done by specifying an offset from which to start counting. [Read more][prerelease-offset]
### `pre_bump_hooks`
@@ -247,7 +247,7 @@ Provide extra variables to the changelog template. [Read more][template-customiz
## Configuration file
-### pyproject.toml, .cz.toml or cz.toml
+### `pyproject.toml`, `.cz.toml` or `cz.toml`
Default and recommended configuration format for a project.
For a **python** project, we recommend adding an entry to your `pyproject.toml`.
@@ -278,7 +278,7 @@ style = [
]
```
-### .cz.json or cz.json
+### `.cz.json` or `cz.json`
Commitizen has support for JSON configuration. Recommended for `NodeJS` projects.
@@ -304,7 +304,7 @@ Commitizen has support for JSON configuration. Recommended for `NodeJS` projects
}
```
-### .cz.yaml or cz.yaml
+### `.cz.yaml` or `cz.yaml`
YAML configuration is supported by Commitizen. Recommended for `Go`, `ansible`, or even `helm` charts projects.
@@ -341,14 +341,14 @@ commitizen:
## Version providers
Commitizen can read and write version from different sources.
-By default, it use the `commitizen` one which is using the `version` field from the commitizen settings.
+By default, it uses the `commitizen` one which is using the `version` field from the Commitizen settings.
But you can use any `commitizen.provider` entrypoint as value for `version_provider`.
Commitizen provides some version providers for some well known formats:
| name | description |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `commitizen` | Default version provider: Fetch and set version in commitizen config. |
+| `commitizen` | Default version provider: Fetch and set version in Commitizen config. |
| `scm` | Fetch the version from git and does not need to set it back |
| `pep621` | Get and set version from `pyproject.toml` `project.version` field |
| `poetry` | Get and set version from `pyproject.toml` `tool.poetry.version` field |
@@ -358,7 +358,7 @@ Commitizen provides some version providers for some well known formats:
| `composer` | Get and set version from `composer.json` `project.version` field |
!!! note
-The `scm` provider is meant to be used with `setuptools-scm` or any packager `*-scm` plugin.
+ The `scm` provider is meant to be used with `setuptools-scm` or any packager `*-scm` plugin.
An example in your `.cz.toml` or `cz.toml` would look like this:
@@ -369,9 +369,9 @@ version_provider = "pep621"
### Custom version provider
-You can add you own version provider by extending `VersionProvider` and exposing it on the `commitizen.provider` entrypoint.
+You can add your own version provider by extending `VersionProvider` and exposing it on the `commitizen.provider` entrypoint.
-Here a quick example of a `my-provider` provider reading and writing version in a `VERSION` file.
+Here is a quick example of a `my-provider` provider reading and writing version in a `VERSION` file.
```python title="my_provider.py"
from pathlib import Path
@@ -408,10 +408,10 @@ setup(
[tag_format]: commands/bump.md#tag_format
[bump_message]: commands/bump.md#bump_message
[major-version-zero]: commands/bump.md#-major-version-zero
-[prerelease-offset]: commands/bump.md#-prerelease_offset
+[prerelease-offset]: commands/bump.md#prerelease_offset
[retry_after_failure]: commands/commit.md#retry
[allow_abort]: commands/check.md#allow-abort
-[version-scheme]: commands/bump.md#version-scheme
+[version-scheme]: commands/bump.md#-version-scheme
[pre_bump_hooks]: commands/bump.md#pre_bump_hooks
[post_bump_hooks]: commands/bump.md#post_bump_hooks
[allowed_prefixes]: commands/check.md#allowed-prefixes
diff --git a/docs/contributing.md b/docs/contributing.md
index 0da1707da6..8389e9370d 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,32 +1,82 @@
-## Contributing to commitizen
-
-First of all, thank you for taking the time to contribute! 🎉
-
-When contributing to [commitizen](https://github.com/commitizen-tools/commitizen), please first create an [issue](https://github.com/commitizen-tools/commitizen/issues) to discuss the change you wish to make before making a change.
-
-If you're a first-time contributor, you can check the issues with [good first issue](https://github.com/commitizen-tools/commitizen/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) tag.
-
-## Install before contributing
-
-1. Install [poetry](https://python-poetry.org/) `>=2.0.0`, installation [pages](https://python-poetry.org/docs/#installing-with-the-official-installer)
-2. Install [gpg](https://gnupg.org), installation [pages](https://gnupg.org/documentation/manuals/gnupg/Installation.html#Installation). For Mac users, you could try [homebrew](https://brew.sh/).
-
-## Before making a pull request
-
-1. Fork [the repository](https://github.com/commitizen-tools/commitizen).
-2. Clone the repository from your GitHub.
-3. Setup development environment through [poetry](https://python-poetry.org/) (`poetry install`).
-4. Setup [pre-commit](https://pre-commit.com/) hook (`poetry setup-pre-commit`)
-5. Check out a new branch and add your modification.
-6. Add test cases for all your changes.
- (We use [CodeCov](https://codecov.io/) to ensure our test coverage does not drop.)
-7. Use [commitizen](https://github.com/commitizen-tools/commitizen) to do git commit. We follow [conventional commits](https://www.conventionalcommits.org/).
-8. Run `poetry all` to ensure you follow the coding style and the tests pass.
-9. Optionally, update the `./docs/README.md` or `docs/images/cli_help` (through running `poetry doc:screenshots`).
-9. **Do not** update the `CHANGELOG.md`, it will be automatically created after merging to `master`.
-10. **Do not** update the versions in the project, they will be automatically updated.
-10. If your changes are about documentation. Run `poetry doc` to serve documentation locally and check whether there is any warning or error.
-11. Send a [pull request](https://github.com/commitizen-tools/commitizen/pulls) 🙏
+## Contributing to Commitizen
+
+First, thank you for taking the time to contribute! 🎉 Your contributions help make Commitizen better for everyone.
+
+When contributing to Commitizen, we encourage you to:
+
+1. First, check out the [issues](https://github.com/commitizen-tools/commitizen/issues) and [Features we won't add](faq.md#features-we-wont-add) to see if there's already a discussion about the change you wish to make.
+2. If there's no discussion, [create an issue](https://github.com/commitizen-tools/commitizen/issues/new) to discuss your proposed changes.
+3. Follow our [development workflow](#development-workflow) and guidelines below.
+
+If you're a first-time contributor, please check out issues labeled [good first issue](https://github.com/commitizen-tools/commitizen/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - these are specifically chosen to be beginner-friendly.
+
+## Prerequisites & Setup
+
+### Required Tools
+
+1. **Python Environment**
+ - Python `>=3.9`
+ - [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer) `>=2.0.0`
+2. **Version Control & Security**
+ - Git
+ - Commitizen
+ - [GPG](https://gnupg.org) for commit signing
+ - [Installation page](https://gnupg.org/documentation/manuals/gnupg/Installation.html#Installation)
+ - For Mac users: `brew install gnupg`
+ - For Windows users: Download from [Gpg4win](https://www.gpg4win.org/)
+ - For Linux users: Use your distribution's package manager (e.g., `apt install gnupg` for Ubuntu)
+
+### Getting Started
+
+1. Fork [Commitizen](https://github.com/commitizen-tools/commitizen)
+2. Clone your fork:
+ ```bash
+ git clone https://github.com/YOUR_USERNAME/commitizen.git
+ cd commitizen
+ ```
+3. Add the upstream repository:
+ ```bash
+ git remote add upstream https://github.com/commitizen-tools/commitizen.git
+ ```
+4. Set up the development environment:
+ ```bash
+ poetry install
+ ```
+5. Set up pre-commit hooks:
+ ```bash
+ poetry setup-pre-commit
+ ```
+
+## Development Workflow
+
+1. **Create a New Branch**
+ ```bash
+ git switch -c feature/your-feature-name
+ # or
+ git switch -c fix/your-bug-fix
+ ```
+2. **Make Your Changes**
+ - Write your code
+ - Add tests for new functionalities or fixes
+ - Update documentation if needed
+ - Follow the existing code style
+3. **Testing**
+ - Run the full test suite: `poetry all`
+ - Ensure test coverage doesn't drop (we use [CodeCov](https://app.codecov.io/gh/commitizen-tools/commitizen))
+ - For documentation changes, run `poetry doc` to check for warnings/errors
+4. **Committing Changes**
+ - Use Commitizen to make commits (we follow [conventional commits](https://www.conventionalcommits.org/))
+ - Example: `cz commit`
+5. **Documentation**
+ - Update `docs/README.md` if needed
+ - For CLI help screenshots: `poetry doc:screenshots`
+ - **DO NOT** update `CHANGELOG.md` (automatically generated)
+ - **DO NOT** update version numbers (automatically handled)
+6. **Pull Request**
+ - Push your changes: `git push origin your-branch-name`
+ - Create a pull request on GitHub
+ - Ensure CI checks pass
+ - Wait for review and address any feedback
## Use of GitHub Labels
@@ -45,8 +95,8 @@ If you're a first-time contributor, you can check the issues with [good first is
* pr-status: wait-for-modification
* pr-status: wait-for-response
* pr-status: ready-to-merge
-* needs: test-case *(pr only)*
-* needs: documentation *(pr only)*
+* needs: test-case *(PR only)*
+* needs: documentation *(PR only)*
* type: feature
* type: bug
* type: documentation
@@ -57,7 +107,7 @@ If you're a first-time contributor, you can check the issues with [good first is
* os: macOS
-### Issue life cycle
+## Issue life cycle
```mermaid
graph TD
@@ -75,7 +125,7 @@ graph TD
close --> output[/close/]
```
-### Pull request life cycle
+## Pull request life cycle
```mermaid
flowchart TD
@@ -103,6 +153,3 @@ flowchart TD
--modification-received-->
review
```
-
-
-[conventional-commits]: https://www.conventionalcommits.org/
diff --git a/docs/customization.md b/docs/customization.md
index 31749d1c83..e97558a308 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -1,4 +1,4 @@
-Customizing commitizen is not hard at all.
+Customizing Commitizen is not hard at all.
We have two different ways to do so.
## 1. Customize in configuration file
@@ -6,7 +6,7 @@ We have two different ways to do so.
The basic steps are:
1. Define your custom committing or bumping rules in the configuration file.
-2. Declare `name = "cz_customize"` in your configuration file, or add `-n cz_customize` when running commitizen.
+2. Declare `name = "cz_customize"` in your configuration file, or add `-n cz_customize` when running Commitizen.
Example:
@@ -170,7 +170,7 @@ commitizen:
| Parameter | Type | Default | Description |
| ----------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type` | `str` | `None` | The type of questions. Valid types: `list`, `select`, `input` and etc. The `select` type provides an interactive searchable list interface. [See More][different-question-types] |
+| `type` | `str` | `None` | The type of questions. Valid types: `list`, `select`, `input`, etc. The `select` type provides an interactive searchable list interface. [See More][different-question-types] |
| `name` | `str` | `None` | The key for the value answered by user. It's used in `message_template` |
| `message` | `str` | `None` | Detail description for the question. |
| `choices` | `list` | `None` | (OPTIONAL) The choices when `type = list` or `type = select`. Either use a list of values or a list of dictionaries with `name` and `value` keys. Keyboard shortcuts can be defined via `key`. See examples above. |
@@ -184,18 +184,18 @@ commitizen:
#### Shortcut keys
-When the [`use_shortcuts`](config.md#settings) config option is enabled, commitizen can show and use keyboard shortcuts to select items from lists directly.
-For example, when using the `cz_conventional_commits` commitizen template, shortcut keys are shown when selecting the commit type. Unless otherwise defined, keyboard shortcuts will be numbered automatically.
+When the [`use_shortcuts`](config.md#settings) config option is enabled, Commitizen can show and use keyboard shortcuts to select items from lists directly.
+For example, when using the `cz_conventional_commits` Commitizen template, shortcut keys are shown when selecting the commit type. Unless otherwise defined, keyboard shortcuts will be numbered automatically.
To specify keyboard shortcuts for your custom choices, provide the shortcut using the `key` parameter in dictionary form for each choice you would like to customize.
## 2. Customize through customizing a class
The basic steps are:
-1. Inheriting from `BaseCommitizen`
+1. Inheriting from `BaseCommitizen`.
2. Give a name to your rules.
-3. Create a python package using `setup.py`, `poetry`, etc
-4. Expose the class as a `commitizen.plugin` entrypoint
+3. Create a python package using `setup.py`, `poetry`, etc.
+4. Expose the class as a `commitizen.plugin` entrypoint.
Check an [example][convcomms] on how to configure `BaseCommitizen`.
@@ -304,7 +304,7 @@ class StrangeCommitizen(BaseCommitizen):
bump_map = {"break": "MAJOR", "new": "MINOR", "fix": "PATCH", "hotfix": "PATCH"}
```
-That's it, your commitizen now supports custom rules, and you can run.
+That's it, your Commitizen now supports custom rules, and you can run.
```bash
cz -n cz_strange bump
@@ -322,9 +322,9 @@ You can customize it of course, and this are the variables you need to add to yo
| `commit_parser` | `str` | NO | Regex which should provide the variables explained in the [changelog description][changelog-des] |
| `changelog_pattern` | `str` | NO | Regex to validate the commits, this is useful to skip commits that don't meet your ruling standards like a Merge. Usually the same as bump_pattern |
| `change_type_map` | `dict` | NO | Convert the title of the change type that will appear in the changelog, if a value is not found, the original will be provided |
-| `changelog_message_builder_hook` | `method: (dict, git.GitCommit) -> dict | list | None` | NO | Customize with extra information your message output, like adding links, this function is executed per parsed commit. Each GitCommit contains the following attrs: `rev`, `title`, `body`, `author`, `author_email`. Returning a falsy value ignore the commit. |
+| `changelog_message_builder_hook` | `method: (dict, git.GitCommit) -> dict | list | None` | NO | Customize with extra information your message output, like adding links, this function is executed per parsed commit. Each GitCommit contains the following attrs: `rev`, `title`, `body`, `author`, `author_email`. Returning a falsy value ignore the commit. |
| `changelog_hook` | `method: (full_changelog: str, partial_changelog: Optional[str]) -> str` | NO | Receives the whole and partial (if used incremental) changelog. Useful to send slack messages or notify a compliance department. Must return the full_changelog |
-| `changelog_release_hook` | `method: (release: dict, tag: git.GitTag) -> dict` | NO | Receives each generated changelog release and its associated tag. Useful to enrich a releases before they are rendered. Must return the update release
+| `changelog_release_hook` | `method: (release: dict, tag: git.GitTag) -> dict` | NO | Receives each generated changelog release and its associated tag. Useful to enrich releases before they are rendered. Must return the update release
```python
from commitizen.cz.base import BaseCommitizen
@@ -395,7 +395,7 @@ class NoSubjectProvidedException(CzException):
Commitizen migrated to a new plugin format relying on `importlib.metadata.EntryPoint`.
Migration should be straight-forward for legacy plugins:
-- Remove the `discover_this` line from you plugin module
+- Remove the `discover_this` line from your plugin module
- Expose the plugin class under as a `commitizen.plugin` entrypoint.
The name of the plugin is now determined by the name of the entrypoint.
@@ -451,16 +451,16 @@ Commitizen gives you the possibility to provide your own changelog template, by:
- as `--template` parameter to both `bump` and `changelog` commands
- either by providing a template with the same name as the default template
-By default, the template used is the `CHANGELOG.md.j2` file from the commitizen repository.
+By default, the template used is the `CHANGELOG.md.j2` file from the Commitizen repository.
### Providing a template with your customization class
-There is 3 parameters available to change the template rendering from your custom `BaseCommitizen`.
+There are 3 parameters available to change the template rendering from your custom `BaseCommitizen`.
| Parameter | Type | Default | Description |
| ----------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------- |
-| `template` | `str` | `None` | Provide your own template name (default to `CHANGELOG.md.j2`) |
-| `template_loader` | `str` | `None` | Override the default template loader (so you can provide template from you customization class) |
+| `template` | `str` | `None` | Provide your own template name (default to `CHANGELOG.md.j2`) |
+| `template_loader` | `str` | `None` | Override the default template loader (so you can provide template from your customization class) |
| `template_extras` | `dict` | `None` | Provide some extra template parameters |
Let's see an example.
@@ -484,14 +484,14 @@ This snippet will:
### Providing a template from the current working directory
-Users can provides their own template from their current working directory (your project root) by:
+Users can provide their own template from their current working directory (your project root) by:
- providing a template with the same name (`CHANGELOG.md.j2` unless overridden by your custom class)
- setting your template path as `template` configuration
- giving your template path as `--template` parameter to `bump` and `changelog` commands
-!!! Note
- The path is relative to the current working directory, aka. your project root most of the time.
+!!! note
+ The path is relative to the current working directory, aka your project root most of the time.
### Template variables
@@ -514,7 +514,7 @@ Each `Change` has the following fields:
| author | `str` | The commit author name |
| author_email | `str` | The commit author email |
-!!! Note
+!!! note
The field values depend on the customization class and/or the settings you provide
The `parents` field can be used to identify merge commits and generate a changelog based on those. Another use case
@@ -524,7 +524,7 @@ When using another template (either provided by a plugin or by yourself), you ca
by:
- defining them in your configuration with the [`extras` settings][extras-config]
-- providing them on the commandline with the `--extra/-e` parameter to `bump` and `changelog` commands
+- providing them on the command line with the `--extra/-e` parameter to `bump` and `changelog` commands
[template-config]: config.md#template
[extras-config]: config.md#extras
diff --git a/docs/exit_codes.md b/docs/exit_codes.md
index af9cb83627..fd92961d38 100644
--- a/docs/exit_codes.md
+++ b/docs/exit_codes.md
@@ -20,7 +20,7 @@ These exit codes can be found in `commitizen/exceptions.py::ExitCode`.
| NoCommitBackupError | 10 | Commit back up file cannot be found |
| NothingToCommitError | 11 | Nothing in staging to be committed |
| CustomError | 12 | `CzException` raised |
-| NoCommandFoundError | 13 | No command found when running commitizen cli (e.g., `cz --debug`) |
+| NoCommandFoundError | 13 | No command found when running Commitizen cli (e.g., `cz --debug`) |
| InvalidCommitMessageError | 14 | The commit message does not pass `cz check` |
| MissingConfigError | 15 | Configuration missed for `cz_customize` |
| NoRevisionError | 16 | No revision found |
diff --git a/docs/external_links.md b/docs/external_links.md
index 388bcc8dea..a90bbd085b 100644
--- a/docs/external_links.md
+++ b/docs/external_links.md
@@ -1,10 +1,10 @@
-> If you have written over commitizen, make a PR and add the link here 💪
+> If you have written over Commitizen, make a PR and add the link here 💪
## Talks
| Name | Speaker | Occasion | Language | Extra |
| ------------------------------------------------------------------------- | --------------- | ---------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| commitizen-tools: What can we gain from crafting a git message convention | Wei Lee | Taipey.py 2020 June Meetup, Remote Python Pizza 2020 | English | [slides](https://speakerdeck.com/leew/commitizen-tools-what-can-we-gain-from-crafting-a-git-message-convention-at-taipey-dot-py) |
+| commitizen-tools: What can we gain from crafting a git message convention | Wei Lee | Taipei.py 2020 June Meetup, Remote Python Pizza 2020 | English | [slides](https://speakerdeck.com/leew/commitizen-tools-what-can-we-gain-from-crafting-a-git-message-convention-at-taipey-dot-py) |
| Automating release cycles | Santiago Fraire | PyAmsterdam June 24, 2020, Online | English | [slides](https://woile.github.io/commitizen-presentation/) |
| [Automatizando Releases con Commitizen y Github Actions][automatizando] | Santiago Fraire | PyConAr 2020, Remote | Español | [slides](https://woile.github.io/automating-releases-github-actions-presentation/#/) |
diff --git a/docs/faq.md b/docs/faq.md
index 29d9f40512..920f533d73 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,3 +1,11 @@
+## Features we won't add
+
+For a comprehensive list of features that have been considered but won't be implemented, please refer to our [issue tracker](https://github.com/commitizen-tools/commitizen/issues?q=is:issue%20state:closed%20label:%22issue-status:%20wont-fix%22%20OR%20label:%22issue-status:%20wont-implement%22).
+
+- Enable multiple locations of config file `.cz.*` [#955](https://github.com/commitizen-tools/commitizen/issues/955)
+- Create a flag to build the changelog from commits in multiple git repositories [#790](https://github.com/commitizen-tools/commitizen/issues/790)
+- Global Configuration [#597](https://github.com/commitizen-tools/commitizen/issues/597)
+
## Support for PEP621
PEP621 establishes a `[project]` definition inside `pyproject.toml`
@@ -52,7 +60,7 @@ It is not affiliated.
Both are used for similar purposes, parsing commits, generating changelog and version we presume.
This one is written in python to make integration easier for python projects and the other serves the JS packages.
-They differ a bit in design, not sure if cz-js does any of this, but these are some of the stuff you can do with this repo (python's commitizen):
+They differ a bit in design, not sure if cz-js does any of this, but these are some things you can do with this repo (python's commitizen):
- create custom rules, version bumps and changelog generation, by default we use the popular conventional commits (I think cz-js allows this).
- single package, install one thing and it will work (cz-js is a monorepo, but you have to install different dependencies AFAIK)
@@ -63,7 +71,7 @@ Where do they cross paths?
If you are using conventional commits in your git history, then you could swap one with the other in theory.
-Regarding the name, [cz-js][cz-js] came first, they used the word commitizen first. When this project was created originally, the creator read "be a good commitizen", and thought it was just a cool word that made sense, and this would be a package that helps you be a good "commit citizen".
+Regarding the name, [cz-js][cz-js] came first, they used the word Commitizen first. When this project was created originally, the creator read "be a good commitizen", and thought it was just a cool word that made sense, and this would be a package that helps you be a good "commit citizen".
[cz-js]: https://github.com/commitizen/cz-cli
@@ -80,17 +88,17 @@ This error was caused by a Python bug on Windows. It's been fixed by [this PR](h
More discussion can be found in issue [#318](https://github.com/commitizen-tools/commitizen/issues/318).
-## Why does commitizen not support CalVer?
+## Why does Commitizen not support CalVer?
`commitizen` could support CalVer alongside SemVer, but in practice implementing CalVer
-creates numerous edge cases that are difficult to maintain ([#385]) and more generally
+creates numerous edge cases that are difficult to maintain ([#385]) and more generally,
mixing the two version schemes may not be a good idea. If CalVer or other custom
versioning scheme is needed, `commitizen` could still be used to standardize commits
and create changelogs, but a separate package should be used for version increments.
Mixing CalVer and SemVer is generally not recommended because each versioning scheme
-serves a different purposes. Diverging from either specification can be confusing to
-users and cause errors with third party tools that don't expect the non-standard format.
+serves a different purpose. Diverging from either specification can be confusing to
+users and cause errors with third-party tools that don't expect the non-standard format.
In the future, `commitizen` may support some implementation of CalVer, but at the time
of writing, there are no plans to implement the feature ([#173]).
@@ -117,7 +125,7 @@ New bumped tags will be in the new format but old ones will still work for:
So given if you change from `myproject-$version` to `${version}` and then `v${version}`,
-your commitizen configuration will look like this:
+your Commitizen configuration will look like this:
```toml
tag_format = "v${version}"
diff --git a/docs/getting_started.md b/docs/getting_started.md
deleted file mode 100644
index 3c6257c363..0000000000
--- a/docs/getting_started.md
+++ /dev/null
@@ -1,119 +0,0 @@
-## Initialize commitizen
-
-If it's your first time, you'll need to create a commitizen configuration file.
-
-The assistant utility will help you set up everything
-
-```sh
-cz init
-```
-
-Alternatively, create a file `.cz.toml` or `cz.toml` in your project's directory.
-
-```toml
-[tool.commitizen]
-version = "0.1.0"
-update_changelog_on_bump = true
-```
-
-## Usage
-
-### Bump version
-
-```sh
-cz bump
-```
-
-This command will bump your project's version, and it will create a tag.
-
-Because of the setting `update_changelog_on_bump`, bump will also create the **changelog**.
-You can also [update files](./commands/bump.md#version_files).
-You can configure the [version scheme](./commands/bump.md#version_scheme) and [version provider](./config.md#version-providers).
-
-There are many more options available, please read the docs for the [bump command](./commands/bump.md).
-
-### Committing
-
-Run in your terminal
-
-```bash
-cz commit
-```
-
-or the shortcut
-
-```bash
-cz c
-```
-
-#### Sign off the commit
-
-Run in the terminal
-
-```bash
-cz commit -- --signoff
-```
-
-or the shortcut
-
-```bash
-cz commit -- -s
-```
-
-### Get project version
-
-Running `cz version` will return the version of commitizen, but if you want
-your project's version you can run:
-
-```sh
-cz version -p
-```
-
-This can be useful in many situations, where otherwise, you would require a way
-to parse the version of your project. Maybe it's simple if you use a `VERSION` file,
-but once you start working with many different projects, it becomes tricky.
-
-A common example is, when you need to send to slack, the changes for the version that you
-just created:
-
-```sh
-cz changelog --dry-run "$(cz version -p)"
-```
-
-### Integration with Pre-commit
-
-Commitizen can lint your commit message for you with `cz check`.
-
-You can integrate this in your [pre-commit](https://pre-commit.com/) config with:
-
-```yaml
----
-repos:
- - repo: https://github.com/commitizen-tools/commitizen
- rev: master
- hooks:
- - id: commitizen
- - id: commitizen-branch
- stages: [pre-push]
-```
-
-After the configuration is added, you'll need to run:
-
-```sh
-pre-commit install --hook-type commit-msg --hook-type pre-push
-```
-
-If you aren't using both hooks, you needn't install both stages.
-
-| Hook | Recommended Stage |
-| ----------------- | ----------------- |
-| commitizen | commit-msg |
-| commitizen-branch | pre-push |
-
-Note that pre-commit discourages using `master` as a revision, and the above command will print a warning. You should replace the `master` revision with the [latest tag](https://github.com/commitizen-tools/commitizen/tags). This can be done automatically with:
-
-```sh
-pre-commit autoupdate
-```
-
-Read more about the `check` command [here](commands/check.md).
diff --git a/docs/images/cli_help/cz___help.svg b/docs/images/cli_help/cz___help.svg
index 098e7df70d..d580cfe619 100644
--- a/docs/images/cli_help/cz___help.svg
+++ b/docs/images/cli_help/cz___help.svg
@@ -1,4 +1,4 @@
-