From 45148ae7664387945c847ec9fff0718653ee4b68 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 17:04:41 +0800 Subject: [PATCH 01/17] docs: fix typos and grammar mistakes --- docs/commands/changelog.md | 10 +++++----- docs/commands/check.md | 22 ++++++++++----------- docs/commands/commit.md | 2 +- docs/config.md | 6 +++--- docs/contributing.md | 32 +++++++++++++++---------------- docs/customization.md | 26 ++++++++++++------------- docs/faq.md | 8 ++++---- docs/third-party-commitizen.md | 2 +- docs/tutorials/auto_check.md | 18 ++++++++--------- docs/tutorials/dev_releases.md | 11 +++-------- docs/tutorials/github_actions.md | 4 ++-- docs/tutorials/gitlab_ci.md | 8 ++++---- docs/tutorials/tag_format.md | 14 +++++++------- docs/tutorials/writing_commits.md | 16 ++++++++-------- 14 files changed, 87 insertions(+), 92 deletions(-) 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..ea033cc411 100644 --- a/docs/commands/commit.md +++ b/docs/commands/commit.md @@ -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/config.md b/docs/config.md index a522312743..b6dd794fb3 100644 --- a/docs/config.md +++ b/docs/config.md @@ -341,7 +341,7 @@ 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: @@ -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 diff --git a/docs/contributing.md b/docs/contributing.md index 0da1707da6..1192e57c0a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -8,25 +8,25 @@ If you're a first-time contributor, you can check the issues with [good first is ## 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/). +1. Install [poetry](https://python-poetry.org/) `>=2.0.0`. See installation [pages](https://python-poetry.org/docs/#installing-with-the-official-installer). +2. Install [gpg](https://gnupg.org). See installation [pages](https://gnupg.org/documentation/manuals/gnupg/Installation.html#Installation). For Mac users, you can use [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. +1. Clone the repository from your GitHub. +1. Set up development environment through [poetry](https://python-poetry.org/) (`poetry install`). +1. Set up [pre-commit](https://pre-commit.com/) hook (`poetry setup-pre-commit`). +1. Checkout a new branch and add your modifications. +1. 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) 🙏 +1. Use [commitizen](https://github.com/commitizen-tools/commitizen) to do git commit. We follow [conventional commits](https://www.conventionalcommits.org/). +1. Run `poetry all` to ensure you follow the coding style and the tests pass. +1. Optionally, update the `./docs/README.md` or `docs/images/cli_help` (through running `poetry doc:screenshots`). +1. **Do not** update the `CHANGELOG.md`; it will be automatically created after merging to `master`. +1. **Do not** update the versions in the project; they will be automatically updated. +1. If your changes are about documentation, run `poetry doc` to serve documentation locally and check whether there are any warnings or errors. +1. Send a [pull request](https://github.com/commitizen-tools/commitizen/pulls) 🙏 ## Use of GitHub Labels @@ -45,8 +45,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 diff --git a/docs/customization.md b/docs/customization.md index 31749d1c83..cef03469e0 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -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. | @@ -192,10 +192,10 @@ To specify keyboard shortcuts for your custom choices, provide the shortcut usin 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`. @@ -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. @@ -455,12 +455,12 @@ By default, the template used is the `CHANGELOG.md.j2` file from the commitizen ### 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. + The path is relative to the current working directory, aka your project root most of the time. ### Template variables @@ -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/faq.md b/docs/faq.md index 29d9f40512..0302efd267 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) @@ -83,14 +83,14 @@ More discussion can be found in issue [#318](https://github.com/commitizen-tools ## 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]). diff --git a/docs/third-party-commitizen.md b/docs/third-party-commitizen.md index 1c8ef8a183..ee454c63d4 100644 --- a/docs/third-party-commitizen.md +++ b/docs/third-party-commitizen.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 2fce57f9bd..d143528767 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/dev_releases.md b/docs/tutorials/dev_releases.md index 8142334754..e2b29fb191 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 7a98abe2be..bcb3fda22c 100644 --- a/docs/tutorials/github_actions.md +++ b/docs/tutorials/github_actions.md @@ -51,7 +51,7 @@ 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` The commitizen action creates an env variable called `REVISION`, containing the -newely created version. +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 85abb3fe6d..85b6a615c3 100644 --- a/docs/tutorials/gitlab_ci.md +++ b/docs/tutorials/gitlab_ci.md @@ -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/tag_format.md b/docs/tutorials/tag_format.md index 59c42bea13..8408b4c801 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 9ba151cc37..d1b2c6645d 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 | From 09b0a459b6e36f0b0b560fb9f13fa9e96b2be367 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 17:19:32 +0800 Subject: [PATCH 02/17] docs: fix typo issues in cli.py, README.md, and contributing.md --- commitizen/cli.py | 2 +- docs/README.md | 18 +++++++++--------- docs/contributing.md | 30 +++++++++++++++--------------- 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/commitizen/cli.py b/commitizen/cli.py index 72d824380d..48506d8ac6 100644 --- a/commitizen/cli.py +++ b/commitizen/cli.py @@ -105,7 +105,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 128602dfb3..ee50ad4582 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,16 +18,16 @@ ## About -Commitizen is release management tool designed for teams. +Commitizen is a release management tool designed for teams. 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. By default, commitizen uses [conventional commits][conventional_commits], but you -can build your own set of rules, and publish them. +can build your own set of rules and publish them. -Using a standardized set of rules to write commits, makes commits easier to read, and enforces writing +Using a standardized set of rules to write commits makes commits easier to read and enforces writing descriptive commits. ### Features @@ -55,7 +55,7 @@ pipx install commitizen pipx upgrade commitizen ``` -Install commitizen using `pip` with `--user` flag: +Install commitizen using `pip` with the `--user` flag: ```bash pip install --user -U commitizen @@ -63,7 +63,7 @@ pip install --user -U commitizen ### Python project -You can add it to your local project using one of the following. +You can add it to your local project using one of the following methods. With `pip`: @@ -99,7 +99,7 @@ brew install commitizen ## Usage -Most of the time this is the only command you'll run: +Most of the time, this is the only command you'll run: ```sh cz bump @@ -120,7 +120,7 @@ $ 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/ +For more information about the topic, go to https://conventionalcommits.org/ optional arguments: -h, --help show this help message and exit @@ -128,7 +128,7 @@ optional arguments: --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- + 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/ commands: @@ -147,7 +147,7 @@ commands: ## 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. +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. argcomplete is installed when you install Commitizen since it's a dependency. diff --git a/docs/contributing.md b/docs/contributing.md index 1192e57c0a..0987771066 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -4,29 +4,29 @@ 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. +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. ## Install before contributing -1. Install [poetry](https://python-poetry.org/) `>=2.0.0`. See installation [pages](https://python-poetry.org/docs/#installing-with-the-official-installer). -2. Install [gpg](https://gnupg.org). See installation [pages](https://gnupg.org/documentation/manuals/gnupg/Installation.html#Installation). For Mac users, you can use [homebrew](https://brew.sh/). +1. Install [poetry](https://python-poetry.org/) `>=2.0.0`. See the installation [pages](https://python-poetry.org/docs/#installing-with-the-official-installer). +2. Install [gpg](https://gnupg.org). See the installation [pages](https://gnupg.org/documentation/manuals/gnupg/Installation.html#Installation). For Mac users, you can use [homebrew](https://brew.sh/). ## Before making a pull request 1. Fork [the repository](https://github.com/commitizen-tools/commitizen). -1. Clone the repository from your GitHub. -1. Set up development environment through [poetry](https://python-poetry.org/) (`poetry install`). -1. Set up [pre-commit](https://pre-commit.com/) hook (`poetry setup-pre-commit`). -1. Checkout a new branch and add your modifications. -1. Add test cases for all your changes. +2. Clone the repository from your GitHub. +3. Set up the development environment through [poetry](https://python-poetry.org/) (`poetry install`). +4. Set up the [pre-commit](https://pre-commit.com/) hook (`poetry setup-pre-commit`). +5. Checkout a new branch and add your modifications. +6. Add test cases for all your changes. (We use [CodeCov](https://codecov.io/) to ensure our test coverage does not drop.) -1. Use [commitizen](https://github.com/commitizen-tools/commitizen) to do git commit. We follow [conventional commits](https://www.conventionalcommits.org/). -1. Run `poetry all` to ensure you follow the coding style and the tests pass. -1. Optionally, update the `./docs/README.md` or `docs/images/cli_help` (through running `poetry doc:screenshots`). -1. **Do not** update the `CHANGELOG.md`; it will be automatically created after merging to `master`. -1. **Do not** update the versions in the project; they will be automatically updated. -1. If your changes are about documentation, run `poetry doc` to serve documentation locally and check whether there are any warnings or errors. -1. Send a [pull request](https://github.com/commitizen-tools/commitizen/pulls) 🙏 +7. Use [commitizen](https://github.com/commitizen-tools/commitizen) to make git commits. 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` (by running `poetry doc:screenshots`). +10. **Do not** update the `CHANGELOG.md`; it will be automatically created after merging to `master`. +11. **Do not** update the versions in the project; they will be automatically updated. +12. If your changes are about documentation, run `poetry doc` to serve documentation locally and check whether there are any warnings or errors. +13. Send a [pull request](https://github.com/commitizen-tools/commitizen/pulls) 🙏 ## Use of GitHub Labels From c1b5ddb190a8d46cd8f856f9df0b970d647334dd Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 22:53:40 +0800 Subject: [PATCH 03/17] docs(README.md): sync help section with the latest `cz --help` command output --- docs/README.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/README.md b/docs/README.md index ee50ad4582..bcc206642d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -115,21 +115,22 @@ Read more in the section [Getting Started](./getting_started.md). ### 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} ... +usage: cz [-h] [--config CONFIG] [--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/ +For more information about the topic go to https://conventionalcommits.org/ -optional arguments: +options: -h, --help show this help message and exit - --config the path of configuration file + --config 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 raise error, e.g: cz -nr 1,2,3 bump. See codes at https://commitizen- - tools.github.io/commitizen/exit_codes/ + -n, --name NAME use the given commitizen (default: cz_conventional_commits) + -nr, --no-raise NO_RAISE + 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/ commands: {init,commit,c,ls,example,info,schema,bump,changelog,ch,check,version} From 8878c453dd667cc3e0e81fa8772f7b4ea38a4e8d Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 23:08:34 +0800 Subject: [PATCH 04/17] docs(README.md): make it easier for readers to understand what Commitizen does --- docs/README.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/README.md b/docs/README.md index bcc206642d..616e7610cc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,17 +18,26 @@ ## About -Commitizen is a 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 From 9549db516d89094b46e38a0215e7084a1047c3d3 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 23:38:41 +0800 Subject: [PATCH 05/17] docs(README.md): move Getting Started to README and improve clarity of the section Closes #1405 --- docs/README.md | 137 ++++++++++++++++++++++++++++++++-------- docs/getting_started.md | 119 ---------------------------------- mkdocs.yml | 1 - 3 files changed, 112 insertions(+), 145 deletions(-) delete mode 100644 docs/getting_started.md diff --git a/docs/README.md b/docs/README.md index 616e7610cc..2a9e79bbfb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -48,81 +48,168 @@ This standardization makes your commit history more readable and meaningful, whi - 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 -[Python](https://www.python.org/downloads/) `3.9+` +### Requirements -[Git][gitscm] `1.8.5.2+` +Before installing Commitizen, ensure you have: -## Installation +- [Python](https://www.python.org/downloads/) `3.9+` +- [Git][gitscm] `1.8.5.2+` -Install commitizen in your system using `pipx` (Recommended, ): +### Installation + +#### Global Installation (Recommended) + +The recommended way to install Commitizen is using `pipx`, which ensures a clean, isolated installation: ```bash +# Install pipx if you haven't already pipx ensurepath + +# Install Commitizen pipx install commitizen + +# Keep it updated pipx upgrade commitizen ``` -Install commitizen using `pip` with the `--user` flag: +If you're on macOS, you can also install Commitizen using Homebrew: ```bash -pip install --user -U commitizen +brew install commitizen ``` -### Python project +#### Project-Specific Installation -You can add it to your local project using one of the following methods. +You can add Commitizen to your Python project using any of these package managers: -With `pip`: +**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: +### Basic Commands -```bash -poetry add commitizen --dev +#### Initialize Commitizen + +To get started, you'll need to set up your configuration. You have two options: + +1. Use the interactive setup: +```sh +cz init ``` -### macOS +2. Manually create a configuration file (`.cz.toml` or `cz.toml`): +```toml +[tool.commitizen] +version = "0.1.0" +update_changelog_on_bump = true +``` -via [homebrew](https://formulae.brew.sh/formula/commitizen): +#### Create Commits -```bash -brew install commitizen +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 +To get your project's version (instead of Commitizen's version): ```sh -cz commit +cz version -p +``` + +This is particularly useful for automation. For example, to preview changelog changes for Slack: +```sh +cz changelog --dry-run "$(cz version -p)" +``` + +#### 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 ``` -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 +> ``` -### Help +For more details about commit validation, see the [check command documentation](commands/check.md). + +## Usage 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/mkdocs.yml b/mkdocs.yml index 6a642161d2..a8a2fe2d44 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" From 2cba21a589cab373aecf105d8dbdd7f529a1b914 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 23:55:40 +0800 Subject: [PATCH 06/17] docs(README.md): improve clarity of README reference section --- docs/README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 65 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index 2a9e79bbfb..22d22f42c9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -209,7 +209,11 @@ pre-commit install --hook-type commit-msg --hook-type pre-push For more details about commit validation, see the [check command documentation](commands/check.md). -## Usage +## Help & Reference + +### Command Line Interface + +Commitizen provides a comprehensive CLI with various commands. Here's the complete reference: @@ -242,31 +246,85 @@ commands: version get the version of the installed commitizen or the current project (default: installed commitizen) ``` +### 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 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. + +### Supported Shells + +- **Bash**: Full support +- **Zsh**: Limited support +- **Fish**: Limited support +- **Tcsh**: Limited support -argcomplete is installed when you install Commitizen since it's a dependency. +### Installation Methods + +#### Global Installation (Recommended) -If Commitizen is installed globally, global activation can be executed: +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 From 299536e0178ed7d0d8531b3ed60687be3430f500 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Mon, 12 May 2025 00:58:47 +0800 Subject: [PATCH 07/17] docs(cli): align cli output with docs --- commitizen/cli.py | 5 ++--- docs/README.md | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/commitizen/cli.py b/commitizen/cli.py index 48506d8ac6..f4a315e7d8 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": [ diff --git a/docs/README.md b/docs/README.md index 22d22f42c9..144c253a81 100644 --- a/docs/README.md +++ b/docs/README.md @@ -221,8 +221,8 @@ Commitizen provides a comprehensive CLI with various commands. Here's the comple $ cz --help usage: cz [-h] [--config CONFIG] [--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/ +Commitizen is a powerful release management tool that helps teams maintain consistent and meaningful commit messages while automating version management. +For more information, please visit https://commitizen-tools.github.io/commitizen options: -h, --help show this help message and exit From aa0e7b6624e0c90cd536b8f0495103b409d1a6b0 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Mon, 12 May 2025 01:56:29 +0800 Subject: [PATCH 08/17] docs(contributing.md): improve readability of contributing docs --- docs/contributing.md | 97 ++++++++++++++++++++++++++++++++------------ 1 file changed, 70 insertions(+), 27 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 0987771066..4ca12765aa 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 the [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`. See the installation [pages](https://python-poetry.org/docs/#installing-with-the-official-installer). -2. Install [gpg](https://gnupg.org). See the installation [pages](https://gnupg.org/documentation/manuals/gnupg/Installation.html#Installation). For Mac users, you can use [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. Set up the development environment through [poetry](https://python-poetry.org/) (`poetry install`). -4. Set up the [pre-commit](https://pre-commit.com/) hook (`poetry setup-pre-commit`). -5. Checkout a new branch and add your modifications. -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 make git commits. 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` (by running `poetry doc:screenshots`). -10. **Do not** update the `CHANGELOG.md`; it will be automatically created after merging to `master`. -11. **Do not** update the versions in the project; they will be automatically updated. -12. If your changes are about documentation, run `poetry doc` to serve documentation locally and check whether there are any warnings or errors. -13. Send a [pull request](https://github.com/commitizen-tools/commitizen/pulls) 🙏 +## 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://codecov.io/)) + - 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 @@ -57,7 +103,7 @@ If you're a first-time contributor, you can check the issues with the [good firs * 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/ From 2cda453ed407987e39678cf1cb569622cbf874e8 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Mon, 12 May 2025 03:05:22 +0800 Subject: [PATCH 09/17] docs(pyproject.toml): fix typo --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 02c6d12762..aab3d7c751 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" From a7ae6824aed1440f37652d95fa9df785eb06587a Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Tue, 13 May 2025 00:29:29 +0800 Subject: [PATCH 10/17] docs(README): update get project version section --- docs/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/README.md b/docs/README.md index 144c253a81..721ab99791 100644 --- a/docs/README.md +++ b/docs/README.md @@ -166,16 +166,16 @@ For all available options, see the [bump command documentation](./commands/bump. #### Get Project Version -To get your project's version (instead of Commitizen's version): ```sh +# Get your project's version (instead of Commitizen's version) cz version -p -``` - -This is particularly useful for automation. For example, to preview changelog changes for Slack: -```sh +# 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. From 0584e901f62f1c6f9e3fc5c51a112e124f1f5d40 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 14 May 2025 23:00:31 +0800 Subject: [PATCH 11/17] docs(README): update installation methods --- docs/README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/README.md b/docs/README.md index 721ab99791..e35cf5e358 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,12 +61,9 @@ Before installing Commitizen, ensure you have: #### Global Installation (Recommended) -The recommended way to install Commitizen is using `pipx`, which ensures a clean, isolated installation: - +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 -# Install pipx if you haven't already -pipx ensurepath - # Install Commitizen pipx install commitizen @@ -74,8 +71,16 @@ pipx install commitizen pipx upgrade commitizen ``` -If you're on macOS, you can also install Commitizen using Homebrew: +**Using uv:** +```bash +# Install commitizen +uv tool install commitizen +# Keep it updated +uv tool upgrade commitizen +``` + +**(For macOS users) Using Homebrew:** ```bash brew install commitizen ``` @@ -85,19 +90,16 @@ brew install commitizen You can add Commitizen to your Python project using any of these package managers: **Using pip:** - ```bash pip install -U commitizen ``` **Using conda:** - ```bash conda install -c conda-forge commitizen ``` **Using Poetry:** - ```bash # For Poetry >= 1.2.0 poetry add commitizen --group dev From a5ede8c50e6d193c142497ab0c60dc1080f36378 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 20:54:23 +0800 Subject: [PATCH 12/17] docs(README): use cli screenshots Closes #1413 --- docs/README.md | 31 +------------------------------ 1 file changed, 1 insertion(+), 30 deletions(-) diff --git a/docs/README.md b/docs/README.md index e35cf5e358..ed1aaef2a1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -217,36 +217,7 @@ For more details about commit validation, see the [check command documentation]( Commitizen provides a comprehensive CLI with various commands. Here's the complete reference: - - -```sh -$ cz --help -usage: cz [-h] [--config CONFIG] [--debug] [-n NAME] [-nr NO_RAISE] {init,commit,c,ls,example,info,schema,bump,changelog,ch,check,version} ... - -Commitizen is a powerful release management tool that helps teams maintain consistent and meaningful commit messages while automating version management. -For more information, please visit https://commitizen-tools.github.io/commitizen - -options: - -h, --help show this help message and exit - --config CONFIG the path of configuration file - --debug use debug mode - -n, --name NAME use the given commitizen (default: cz_conventional_commits) - -nr, --no-raise NO_RAISE - 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/ - -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 --help](images/cli_help/cz___help.svg) ### Quick Reference From cc45de4c5bf5062709e6d30bc70e12357c6556dd Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 21:13:54 +0800 Subject: [PATCH 13/17] docs: fix link warnings and minor grammar issues --- docs/commands/bump.md | 10 +++++----- docs/config.md | 24 ++++++++++++------------ docs/customization.md | 4 ++-- docs/tutorials/github_actions.md | 4 ++-- docs/tutorials/gitlab_ci.md | 4 ++-- docs/tutorials/jenkins_pipeline.md | 2 +- docs/tutorials/monorepo_guidance.md | 4 ++-- 7 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/commands/bump.md b/docs/commands/bump.md index efdba76257..6eb5b55c54 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). @@ -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] diff --git a/docs/config.md b/docs/config.md index b6dd794fb3..1ea02d5f67 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` @@ -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. @@ -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: @@ -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/customization.md b/docs/customization.md index cef03469e0..805173e900 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -490,7 +490,7 @@ Users can provide their own template from their current working directory (your - setting your template path as `template` configuration - giving your template path as `--template` parameter to `bump` and `changelog` commands -!!! Note +!!! 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 diff --git a/docs/tutorials/github_actions.md b/docs/tutorials/github_actions.md index bcb3fda22c..4f50aaf4e7 100644 --- a/docs/tutorials/github_actions.md +++ b/docs/tutorials/github_actions.md @@ -41,14 +41,14 @@ 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 newly created version. diff --git a/docs/tutorials/gitlab_ci.md b/docs/tutorials/gitlab_ci.md index 85b6a615c3..6f6d53a57e 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: diff --git a/docs/tutorials/jenkins_pipeline.md b/docs/tutorials/jenkins_pipeline.md index fb87820c4c..2b9ad173d3 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 792c8c224f..434899f86f 100644 --- a/docs/tutorials/monorepo_guidance.md +++ b/docs/tutorials/monorepo_guidance.md @@ -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) From 5ea8026c8922f3d197d90d8ea27e4a31055dc753 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 21:22:04 +0800 Subject: [PATCH 14/17] docs(pull_request_template): add broken link check to the checklist --- .github/pull_request_template.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e28480e5b9..5686474709 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 From 63787d3910fa7fd13c267ef0b8c61fe18ea204f5 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 21:27:41 +0800 Subject: [PATCH 15/17] docs(contributing): update codecov link --- docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index 4ca12765aa..336f83352a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -58,7 +58,7 @@ If you're a first-time contributor, you can check the issues with the [good firs - Follow the existing code style 3. **Testing** - Run the full test suite: `poetry all` - - Ensure test coverage doesn't drop (we use [CodeCov](https://codecov.io/)) + - 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/)) From 82a42c8b483be7667021ef1b0c6c2a44315d890f Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 21:44:23 +0800 Subject: [PATCH 16/17] docs(README): update project specific installation methods --- docs/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/README.md b/docs/README.md index ed1aaef2a1..e0c3fed747 100644 --- a/docs/README.md +++ b/docs/README.md @@ -108,6 +108,16 @@ poetry add commitizen --group dev poetry add commitizen --dev ``` +**Using uv:** +```bash +uv add commitizen +``` + +**Using pdm:** +```bash +pdm add -d commitizen +``` + ### Basic Commands #### Initialize Commitizen From 953e87841ca1f04a009a12c8d7388ce5e84449dc Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 22:03:19 +0800 Subject: [PATCH 17/17] docs: capitalize commitizen for consistency --- docs/README.md | 2 +- docs/commands/bump.md | 26 +++++++++---------- docs/commands/commit.md | 10 +++---- docs/commands/init.md | 2 +- docs/commands/version.md | 2 +- docs/config.md | 6 ++--- docs/contributing.md | 2 +- docs/customization.md | 12 ++++----- docs/exit_codes.md | 2 +- docs/external_links.md | 2 +- docs/faq.md | 6 ++--- docs/third-party-commitizen.md | 4 +-- docs/tutorials/auto_prepare_commit_message.md | 8 +++--- docs/tutorials/github_actions.md | 4 +-- docs/tutorials/monorepo_guidance.md | 2 +- docs/tutorials/writing_commits.md | 2 +- 16 files changed, 46 insertions(+), 46 deletions(-) diff --git a/docs/README.md b/docs/README.md index e0c3fed747..9bb1555721 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) --- diff --git a/docs/commands/bump.md b/docs/commands/bump.md index 6eb5b55c54..ee3d77430a 100644 --- a/docs/commands/bump.md +++ b/docs/commands/bump.md @@ -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 @@ -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/commit.md b/docs/commands/commit.md index ea033cc411..febaee3cf2 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 diff --git a/docs/commands/init.md b/docs/commands/init.md index 01e1db6be8..a799c44810 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 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 1ea02d5f67..5ca2c5d788 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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` @@ -341,14 +341,14 @@ commitizen: ## Version providers Commitizen can read and write version from different sources. -By default, it uses 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 | diff --git a/docs/contributing.md b/docs/contributing.md index 336f83352a..e9e162d2df 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -61,7 +61,7 @@ If you're a first-time contributor, you can check the issues with the [good firs - 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/)) + - Use Commitizen to make commits (we follow [conventional commits](https://www.conventionalcommits.org/)) - Example: `cz commit` 5. **Documentation** - Update `docs/README.md` if needed diff --git a/docs/customization.md b/docs/customization.md index 805173e900..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: @@ -184,8 +184,8 @@ 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 @@ -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 @@ -451,7 +451,7 @@ 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 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..24e4127d86 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 0302efd267..ceabac2e10 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -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,7 +80,7 @@ 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, @@ -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/third-party-commitizen.md b/docs/third-party-commitizen.md index ee454c63d4..ee65255934 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 diff --git a/docs/tutorials/auto_prepare_commit_message.md b/docs/tutorials/auto_prepare_commit_message.md index 7e8295b7c8..84ac62b689 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/github_actions.md b/docs/tutorials/github_actions.md index 4f50aaf4e7..bf08eb3bc5 100644 --- a/docs/tutorials/github_actions.md +++ b/docs/tutorials/github_actions.md @@ -50,7 +50,7 @@ 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` -The commitizen action creates an env variable called `REVISION`, containing the +Commitizen action creates an env variable called `REVISION`, containing the newly created version. ```yaml @@ -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 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/monorepo_guidance.md b/docs/tutorials/monorepo_guidance.md index 434899f86f..6f15a87247 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: diff --git a/docs/tutorials/writing_commits.md b/docs/tutorials/writing_commits.md index d1b2c6645d..7d9139929c 100644 --- a/docs/tutorials/writing_commits.md +++ b/docs/tutorials/writing_commits.md @@ -1,6 +1,6 @@ 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 +By default, Commitizen uses the known [conventional commits][conventional_commits], but you can create your own following the documentation information over at [customization][customization].