diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e28480e5b..568647470 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 if there are any broken links 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/commitizen/cli.py b/commitizen/cli.py index 72d824380..f4a315e7d 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/docs/README.md b/docs/README.md index 128602dfb..9bb155572 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ [![Codecov](https://img.shields.io/codecov/c/github/commitizen-tools/commitizen.svg?style=flat-square)](https://codecov.io/gh/commitizen-tools/commitizen) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?style=flat-square&logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) -![Using commitizen cli](images/demo.gif) +![Using Commitizen cli](images/demo.gif) --- @@ -18,17 +18,26 @@ ## 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 @@ -39,137 +48,266 @@ descriptive commits. - 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) -## Requirements +## Getting Started + +### 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 +``` + +2. Manually create a configuration file (`.cz.toml` or `cz.toml`): +```toml +[tool.commitizen] +version = "0.1.0" +update_changelog_on_bump = true +``` + +#### Create Commits + +Create standardized commits using: +```sh +cz commit +# or use the shortcut +cz c ``` -## Usage +To sign off your commits: +```sh +cz commit -- --signoff +# or use the shortcut +cz commit -- -s +``` -Most of the time this is the only command you'll run: +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](./commands/bump.md#version_files) +- [Version scheme](./commands/bump.md#version_scheme) +- [Version provider](./config.md#version-providers) + +For all available options, see the [bump command documentation](./commands/bump.md). + +### Advanced Usage + +#### Get Project Version + +```sh +# Get your project's version (instead of Commitizen's version) +cz version -p +# Preview changelog changes +cz changelog --dry-run "$(cz version -p)" +``` + +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 -cz commit +pre-commit install --hook-type commit-msg --hook-type pre-push ``` -Read more in the section [Getting Started](./getting_started.md). +| 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](commands/check.md). + +## Help & Reference + +### Command Line Interface -### Help +Commitizen provides a comprehensive CLI with various commands. Here's the complete reference: + +![cz --help](images/cli_help/cz___help.svg) + +### 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](./exit_codes.md) +- [Configuration Guide](./config.md) +- [Command Documentation](./commands/init.md) + +### 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 detailed documentation, 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 efdba7625..ee3d77430 100644 --- a/docs/commands/bump.md +++ b/docs/commands/bump.md @@ -72,7 +72,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). @@ -116,7 +116,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 +148,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 +174,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` @@ -332,11 +332,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 +355,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 +367,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 +387,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 +403,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 +477,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 +499,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 +510,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 +521,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 +532,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 cbf22b15a..aee1a0e07 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 e45ecd86c..33e41e04f 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 7760a2b88..febaee3cf 100644 --- a/docs/commands/commit.md +++ b/docs/commands/commit.md @@ -1,4 +1,4 @@ -![Using commitizen cli](../images/demo.gif) +![Using Commitizen cli](../images/demo.gif) ## About @@ -20,14 +20,14 @@ case for this is to [automatically prepare a commit message](../tutorials/auto_p ### git options -`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: +`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: ```sh cz commit -- # e.g., cz commit --dry-run -- -a -S ``` -For example, using the `-S` option on `git commit` to sign a commit is now commitizen compatible: `cz c -- -S` +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`. @@ -37,7 +37,7 @@ For example, using the `-S` option on `git commit` to sign a commit is now commi 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 +configuration option to `true`. Running `cz commit --no-retry` makes Commitizen ignore `retry_after_failure`, forcing a new commit message to be prompted. ### Commit message length limit @@ -45,7 +45,7 @@ a new commit message to be prompted. 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. +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.** Specifically, for `ConventionalCommitsCz` the length only counts from the type of change to the subject, diff --git a/docs/commands/init.md b/docs/commands/init.md index 01e1db6be..a799c4481 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -4,7 +4,7 @@ ## Example -To start using commitizen, the recommended approach is to run +To start using Commitizen, the recommended approach is to run ```sh cz init diff --git a/docs/commands/version.md b/docs/commands/version.md index 9a8176b45..4d2e6a032 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 a52231274..5ca2c5d78 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 0da1707da..e9e162d2d 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,32 +1,78 @@ ## Contributing to commitizen -First of all, thank you for taking the time to contribute! 🎉 +First, 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) 🙏 +If you're a first-time contributor, you can check the issues with the [good first issue](https://github.com/commitizen-tools/commitizen/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) tag. + +## 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 +91,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 +103,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 +121,7 @@ graph TD close --> output[/close/] ``` -### Pull request life cycle +## Pull request life cycle ```mermaid flowchart TD @@ -103,6 +149,3 @@ flowchart TD --modification-received--> review ``` - - -[conventional-commits]: https://www.conventionalcommits.org/ diff --git a/docs/customization.md b/docs/customization.md index 31749d1c8..e97558a30 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 af9cb8362..fd92961d3 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 388bcc8de..24e4127d8 100644 --- a/docs/external_links.md +++ b/docs/external_links.md @@ -1,4 +1,4 @@ -> 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 diff --git a/docs/faq.md b/docs/faq.md index 29d9f4051..ceabac2e1 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -52,7 +52,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 +63,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 +80,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 +117,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 3c6257c36..000000000 --- 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/third-party-commitizen.md b/docs/third-party-commitizen.md index 1c8ef8a18..ee6525593 100644 --- a/docs/third-party-commitizen.md +++ b/docs/third-party-commitizen.md @@ -17,9 +17,9 @@ pip install conventional-JIRA ### [GitHub JIRA Conventional](https://pypi.org/project/cz-github-jira-conventional/) -This plugin extends the commitizen tools by: +This plugin extends the Commitizen tools by: -- requiring a JIRA issue id in the commit message +- requiring a JIRA issue ID in the commit message - creating links to GitHub commits in the CHANGELOG.md - creating links to JIRA issues in the CHANGELOG.md @@ -101,7 +101,7 @@ See the [README][1] for instructions on configuration ## Third-Party Commitizen Providers -Commitizen can read and write version from different sources. In addition to the native providers, some alternative version sources are available as PyPI packages (installable with `pip`). +Commitizen can read and write version from different sources. In addition to the native providers, some alternative version sources are available as PyPI packages (installable with `pip`). ### [commitizen-deno-provider](https://pypi.org/project/commitizen-deno-provider/) diff --git a/docs/tutorials/auto_check.md b/docs/tutorials/auto_check.md index 2fce57f9b..d14352876 100644 --- a/docs/tutorials/auto_check.md +++ b/docs/tutorials/auto_check.md @@ -6,9 +6,9 @@ To automatically check a commit message prior to committing, you can use a [git ## How to -There are two common methods for installing the hook: +There are two common methods for installing the hooks: -### Method 1: Add git hook through [pre-commit](https://pre-commit.com/) +### Method 1: Add a git hook through [pre-commit](https://pre-commit.com/) - Step 1: Install [pre-commit](https://pre-commit.com/) @@ -16,7 +16,7 @@ There are two common methods for installing the hook: python -m pip install pre-commit ``` -- Step 2: Create `.pre-commit-config.yaml` at your root directory with the following content +- Step 2: Create `.pre-commit-config.yaml` in your root directory with the following content ```yaml --- @@ -28,19 +28,19 @@ repos: stages: [commit-msg] ``` -- Step 3: Install the configuration into git hook through `pre-commit` +- Step 3: Install the configuration into the git hook through `pre-commit` ```bash pre-commit install --hook-type commit-msg ``` -### Method 2: Manually add git hook +### Method 2: Manually add a git hook -The command might be included inside of a Git hook (inside of `.git/hooks/` at the root of the project). +The command might be included inside a Git hook (inside `.git/hooks/` at the root of the project). The selected hook might be the file called commit-msg. -This example shows how to use the check command inside of commit-msg. +This example shows how to use the check command inside commit-msg. At the root of the project: @@ -62,7 +62,7 @@ Where `$1` is the name of the temporary file that contains the current commit me The `--commit-msg-file` flag is required, not optional. -Each time you create a commit, automatically, this hook will analyze it. -If the commit message is invalid, it'll be rejected. +Each time you create a commit, this hook will automatically analyze it. +If the commit message is invalid, it will be rejected. The commit should follow the given committing rules; otherwise, it won't be accepted. diff --git a/docs/tutorials/auto_prepare_commit_message.md b/docs/tutorials/auto_prepare_commit_message.md index 7e8295b7c..84ac62b68 100644 --- a/docs/tutorials/auto_prepare_commit_message.md +++ b/docs/tutorials/auto_prepare_commit_message.md @@ -2,7 +2,7 @@ ## About -It can be desirable to use commitizen for all types of commits (i.e. regular, merge, +It can be desirable to use Commitizen for all types of commits (i.e. regular, merge, squash) so that the complete git history adheres to the commit message convention without ever having to call `cz commit`. @@ -18,10 +18,10 @@ To automatically perform arbitrary cleanup steps after a successful commit you c > This hook is invoked by git-commit. It takes no parameters, and is invoked after a > commit is made. -A combination of these two hooks allows for enforcing the usage of commitizen so that -whenever a commit is about to be created, commitizen is used for creating the commit +A combination of these two hooks allows for enforcing the usage of Commitizen so that +whenever a commit is about to be created, Commitizen is used for creating the commit message. Running `git commit` or `git commit -m "..."` for example, would trigger -commitizen and use the generated commit message for the commit. +Commitizen and use the generated commit message for the commit. ## Installation diff --git a/docs/tutorials/dev_releases.md b/docs/tutorials/dev_releases.md index 814233475..e2b29fb19 100644 --- a/docs/tutorials/dev_releases.md +++ b/docs/tutorials/dev_releases.md @@ -5,9 +5,7 @@ To make use of a `.dev` suffix, as per [PEP440](https://peps.python.org/pep-0440/#developmental-releases). -If more than one active branch attempts to create a tag, relative to the main -branch, there is the possibility that each will attempt to create the _same_ -tag, resulting in a collision. +If multiple active branches attempt to create a tag relative to the main branch, there is a possibility that they will attempt to create the _same_ tag, resulting in a collision. Developmental releases aim to avoid this by including a `.dev` segment which includes a non-negative integer unique to that workflow: @@ -19,9 +17,7 @@ X.Y.devN !!! note As noted in [PEP440](https://peps.python.org/pep-0440/#developmental-releases), - although developmental releases are useful in avoiding the situation - described above, depending on the value passed as the developmental - release, they can be _"difficult to parse for human readers"_. + while developmental releases help avoid the situation described above, they can be _"difficult to parse for human readers"_ depending on the value passed as the developmental release. ## How to @@ -64,8 +60,7 @@ Equally, as the developmental release needs only a non-negative integer, it is possible to use the Unix time (i.e. the number of seconds since 1st January 1970 UTC). -This would create the possibility of a collision if two builds occur at -precisely the same second but this may be sufficient for many cases: +This approach could potentially create a collision if two builds occur at precisely the same second, but it may be sufficient for many use cases: ```sh --devrelease $(date +%s) diff --git a/docs/tutorials/github_actions.md b/docs/tutorials/github_actions.md index 7a98abe2b..bf08eb3bc 100644 --- a/docs/tutorials/github_actions.md +++ b/docs/tutorials/github_actions.md @@ -41,17 +41,17 @@ jobs: Push to master and that's it. -### Creating a github release +### Creating a GitHub release You can modify the previous action. Add the variable `changelog_increment_filename` in the `commitizen-action`, specifying where to output the content of the changelog for the newly created version. -And then add a step using a github action to create the release: `softprops/action-gh-release` +And then add a step using a GitHub action to create the release: `softprops/action-gh-release` -The commitizen action creates an env variable called `REVISION`, containing the -newely created version. +Commitizen action creates an env variable called `REVISION`, containing the +newly created version. ```yaml - name: Create bump and changelog @@ -119,7 +119,7 @@ jobs: ./scripts/publish ``` -Notice that we are using poetry, and we are calling a bash script in `./scripts/publish`. You should configure the action, and the publish with your tools (twine, poetry, etc.). Check [commitizen example](https://github.com/commitizen-tools/commitizen/blob/master/scripts/publish) +Notice that we are using poetry, and we are calling a bash script in `./scripts/publish`. You should configure the action, and publish with your tools (twine, poetry, etc.). Check [Commitizen example](https://github.com/commitizen-tools/commitizen/blob/master/scripts/publish) You can also use [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish) to publish your package. Push the changes and that's it. diff --git a/docs/tutorials/gitlab_ci.md b/docs/tutorials/gitlab_ci.md index 85abb3fe6..6f6d53a57 100644 --- a/docs/tutorials/gitlab_ci.md +++ b/docs/tutorials/gitlab_ci.md @@ -12,9 +12,9 @@ _Goal_: Bump a new version every time that a change occurs on the `master` branc 4. For simplification, we store the software version in a file called `VERSION`. You can use any file that you want as `commitizen` supports it. 5. The commit message executed automatically by the `CI` must include `[skip-ci]` in the message; otherwise, the process will generate a loop. You can define the message structure in [commitizen](../commands/bump.md) as well. -### Gitlab Configuration +### GitLab Configuration -To be able to change files and push new changes with `Gitlab CI` runners, we need to have a `ssh` key and configure a git user. +To be able to change files and push new changes with `GitLab CI` runners, we need to have a `ssh` key and configure a git user. First, let's create a `ssh key`. The only requirement is to create it without a passphrase: @@ -38,7 +38,7 @@ The latest step is to create a `deploy key.` To do this, we should create it und If you have more projects under the same organization, you can reuse the deploy key created before, but you will have to repeat the step where we have created the environment variables (ssh key, email, and username). -tip: If the CI raise some errors, try to unprotected the private key. +Tip: If the CI raise some errors, try to unprotect the private key. ### Defining GitLab CI Pipeline @@ -105,9 +105,9 @@ auto-bump: - variables ``` -So, every time that a developer push to any branch, the `test` job is executed. If the branch is `master` and the test jobs success, the `auto-bump` takes place. -To be able to push using the Gitlab runner, we have to set the ssh key, configure git, and finally execute the auto bump. +So, every time that a developer pushes to any branch, the `test` job is executed. If the branch is `master` and the test jobs succeed, the `auto-bump` takes place. +To be able to push using the GitLab runner, we have to set the SSH key, configure git, and finally execute the auto bump. -After merging the new changed into master, we have the final result: +After merging the new changes into master, we have the final result: ![gitlab final ci result](../images/gitlab_ci/gitlab_final_ci_result.png) diff --git a/docs/tutorials/jenkins_pipeline.md b/docs/tutorials/jenkins_pipeline.md index fb87820c4..2b9ad173d 100644 --- a/docs/tutorials/jenkins_pipeline.md +++ b/docs/tutorials/jenkins_pipeline.md @@ -47,7 +47,7 @@ def useCz(String authorName = 'Jenkins CI Server', String authorEmail = 'your-je ``` !!! warning - Using jenkins pipeline with any git plugin may require many different configurations, + Using jenkins pipeline with any git plugin may require many configurations, you'll have to tinker with it until your pipelines properly detects git events. Check your webhook in your git repository and check the "behaviors" and "build strategies" in your pipeline settings. diff --git a/docs/tutorials/monorepo_guidance.md b/docs/tutorials/monorepo_guidance.md index 792c8c224..6f15a8724 100644 --- a/docs/tutorials/monorepo_guidance.md +++ b/docs/tutorials/monorepo_guidance.md @@ -1,4 +1,4 @@ -# Configuring commitizen in a monorepo +# Configuring Commitizen in a monorepo This tutorial assumes the monorepo layout is designed with multiple components that can be released independently of each other, it also assumes that conventional commits with scopes are in use. Some suggested layouts: @@ -56,9 +56,9 @@ In order to filter the correct commits for each component, you'll have to come u For example: - Trigger the pipeline based on the changed path, which can have some downsides, as you'll rely on the developer not including files from other files - - [github actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore) uses `path` + - [GitHub actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore) uses `path` - [Jenkins](https://www.jenkins.io/doc/book/pipeline/syntax/#built-in-conditions) uses `changeset` - - [Gitlab](https://docs.gitlab.com/ee/ci/yaml/#ruleschanges) uses `rules:changes` + - [GitLab](https://docs.gitlab.com/ee/ci/yaml/#ruleschanges) uses `rules:changes` - Filter certain pattern of the commit message (recommended) diff --git a/docs/tutorials/tag_format.md b/docs/tutorials/tag_format.md index 59c42bea1..8408b4c80 100644 --- a/docs/tutorials/tag_format.md +++ b/docs/tutorials/tag_format.md @@ -10,7 +10,7 @@ tag_format: $version version_scheme: pep440 ``` -As this is the default value so you don't have to specify it. +As this is the default value, you don't have to specify it. This setting means that: @@ -52,7 +52,7 @@ You will obviously want to keep all those features working as expected. Commitizen can deal with it as long as you provide the legacy tag format in the configuration. -Using the previous example, let say you want to move from `v${version}` to `component-${version}`. +Using the previous example, let's say you want to move from `v${version}` to `component-${version}`. Then `component-${version}` will be the new tag format and `v${version}` the legacy one. ```yaml @@ -62,14 +62,14 @@ legacy_tag_formats: - v${version} ``` -This way, you won't loose your version history, you'll still be able to generate you changelog properly -and on the next version bump, your last version in the form `v${version}` will be properly recognizef if you use the `scm` version provider. +This way, you won't lose your version history, you'll still be able to generate your changelog properly, +and on the next version bump, your last version in the form `v${version}` will be properly recognized if you use the `scm` version provider. Your new tag will be in the form `component-${version}`. ## Known tags to ignore -Now let's say you have some known tags you want to ignore, either because they are not versions, either because they are not versions of the component you are dealing with. -As a consequence, you don't want them to trigger a warning because Commitizen detected an unknown tag format: +Now let's say you have some known tags you want to ignore, either because they are not versions, or because they are not versions of the component you are dealing with. +As a consequence, you don't want them to trigger a warning because Commitizen detected an unknown tag format. Then you can tell Commitizen about it using the [`ignored_tag_formats`](../config.md#ignored_tag_formats) setting: @@ -93,7 +93,7 @@ This will ignore: It will match any string from any length. This allows to exclude by prefix, whether it is followed by a version or not. !!! tip - If you don't want to be warned when Commitizen detect an unknown tag, you can by setting: + If you don't want to be warned when Commitizen detects an unknown tag, you can do so by setting: ``` [tool.commitizen] ignored_tag_formats = ["*"] diff --git a/docs/tutorials/writing_commits.md b/docs/tutorials/writing_commits.md index 9ba151cc3..7d9139929 100644 --- a/docs/tutorials/writing_commits.md +++ b/docs/tutorials/writing_commits.md @@ -1,21 +1,21 @@ For this project to work well in your pipeline, a commit convention must be followed. -By default commitizen uses the known [conventional commits][conventional_commits], but -you can create your own following the docs information over at +By default, Commitizen uses the known [conventional commits][conventional_commits], but +you can create your own following the documentation information over at [customization][customization]. ## Conventional commits If you are using [conventional commits][conventional_commits], the most important thing to know is that you must begin your commits with at least one of these tags: -`fix`, `feat`. And if you introduce a breaking change, then, you must +`fix`, `feat`. And if you introduce a breaking change, then you must add to your commit body the following `BREAKING CHANGE`. -Using these 3 keywords will allow the proper identification of the semantic version. +Using these three keywords will allow the proper identification of the semantic version. Of course, there are other keywords, but I'll leave it to the reader to explore them. ## Writing commits -Now to the important part, when writing commits, it's important to think about: +Now to the important part: when writing commits, it's important to think about: - Your future self - Your colleagues @@ -23,16 +23,16 @@ Now to the important part, when writing commits, it's important to think about: You may think this is trivial, but it's not. It's important for the reader to understand what happened. -Emojis may be added as well (e.g. see [cz-emoji][cz_emoji]), which requires the `utf-8`, or equivalent, character encoding to support unicode characters. By default, `commitizen` uses the `utf-8` character encoding, but a different encoding may be set through the `encoding` [configuration option][configuration]. +Emojis may be added as well (e.g., see [cz-emoji][cz_emoji]), which requires the `utf-8`, or equivalent, character encoding to support unicode characters. By default, `commitizen` uses the `utf-8` character encoding, but a different encoding may be set through the `encoding` [configuration option][configuration]. ### Recommendations - **Keep the message short**: Makes the list of commits more readable (~50 chars). - **Talk imperative**: Follow this rule: `If applied, this commit will ` -- **Think about the CHANGELOG**: Your commits will probably end up in the changelog +- **Think about the CHANGELOG**: Your commits will probably end up in the changelog, so try writing for it, but also keep in mind that you can skip sending commits to the CHANGELOG by using different keywords (like `build`). -- **Use a commit per new feature**: if you introduce multiple things related to the same +- **Use a commit per new feature**: If you introduce multiple things related to the same commit, squash them. This is useful for auto-generating CHANGELOG. | Do's | Don'ts | diff --git a/mkdocs.yml b/mkdocs.yml index 6a642161d..a8a2fe2d4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,7 +31,6 @@ edit_uri: "" nav: - Introduction: "README.md" - - Getting Started: "getting_started.md" - Commands: - init: "commands/init.md" - commit: "commands/commit.md" diff --git a/pyproject.toml b/pyproject.toml index 02c6d1276..aab3d7c75 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -257,7 +257,7 @@ all.sequence = [ "check-commit", ] -"doc:screenshots".help = "Render documentation screeenshots" +"doc:screenshots".help = "Render documentation screenshots" "doc:screenshots".script = "scripts.gen_cli_help_screenshots:gen_cli_help_screenshots" "doc:build".help = "Build the documentation"