From fe72043eeec8ffdd34d721ada65c45c622acdac2 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sat, 17 May 2025 19:59:18 +0800 Subject: [PATCH 01/35] refactor(check): remove unnecessary variable --- commitizen/commands/check.py | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/commitizen/commands/check.py b/commitizen/commands/check.py index 087db03ea5..a0d06cbc47 100644 --- a/commitizen/commands/check.py +++ b/commitizen/commands/check.py @@ -72,15 +72,11 @@ def __call__(self): raise NoCommitsFoundError(f"No commit found with range: '{self.rev_range}'") pattern = self.cz.schema_pattern() - ill_formatted_commits = [ - commit - for commit in commits - if not self.validate_commit_message(commit.message, pattern) - ] displayed_msgs_content = "\n".join( [ f'commit "{commit.rev}": "{commit.message}"' - for commit in ill_formatted_commits + for commit in commits + if not self.validate_commit_message(commit.message, pattern) ] ) if displayed_msgs_content: From 7fd6ce33d59f90f0a85826b54224aa063ddfdc70 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sat, 17 May 2025 20:05:39 +0800 Subject: [PATCH 02/35] refactor(check): simplify code --- commitizen/commands/check.py | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/commitizen/commands/check.py b/commitizen/commands/check.py index a0d06cbc47..1e3b8464e1 100644 --- a/commitizen/commands/check.py +++ b/commitizen/commands/check.py @@ -88,24 +88,21 @@ def __call__(self): ) out.success("Commit validation: successful!") + def _get_commit_message(self) -> str | None: + if self.commit_msg_file is None: + # Get commit message from command line (--message) + return self.commit_msg + + with open(self.commit_msg_file, encoding=self.encoding) as commit_file: + # Get commit message from file (--commit-msg-file) + return commit_file.read() + def _get_commits(self): - msg = None - # Get commit message from file (--commit-msg-file) - if self.commit_msg_file is not None: - # Enter this branch if commit_msg_file is "". - with open(self.commit_msg_file, encoding=self.encoding) as commit_file: - msg = commit_file.read() - # Get commit message from command line (--message) - elif self.commit_msg is not None: - msg = self.commit_msg - if msg is not None: - msg = self._filter_comments(msg) - return [git.GitCommit(rev="", title="", body=msg)] + if (msg := self._get_commit_message()) is not None: + return [git.GitCommit(rev="", title="", body=self._filter_comments(msg))] # Get commit messages from git log (--rev-range) - if self.rev_range: - return git.get_commits(end=self.rev_range) - return git.get_commits() + return git.get_commits(end=self.rev_range or "HEAD") @staticmethod def _filter_comments(msg: str) -> str: From a8094aebad266040ef07f118a96c88a93f4aecf8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 22 May 2025 03:16:18 +0000 Subject: [PATCH 03/35] =?UTF-8?q?bump:=20version=204.8.1=20=E2=86=92=204.8?= =?UTF-8?q?.2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .pre-commit-config.yaml | 2 +- CHANGELOG.md | 7 +++++++ commitizen/__version__.py | 2 +- pyproject.toml | 4 ++-- 4 files changed, 11 insertions(+), 4 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f1aef91193..4e108eb9b9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -48,7 +48,7 @@ repos: - tomli - repo: https://github.com/commitizen-tools/commitizen - rev: v4.8.1 # automatically updated by Commitizen + rev: v4.8.2 # automatically updated by Commitizen hooks: - id: commitizen - id: commitizen-branch diff --git a/CHANGELOG.md b/CHANGELOG.md index 9904ae3bbf..5b737a851a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +## v4.8.2 (2025-05-22) + +### Refactor + +- **check**: simplify code +- **check**: remove unnecessary variable + ## v4.8.1 (2025-05-22) ### Refactor diff --git a/commitizen/__version__.py b/commitizen/__version__.py index 1969a66ecd..8e288a597c 100644 --- a/commitizen/__version__.py +++ b/commitizen/__version__.py @@ -1 +1 @@ -__version__ = "4.8.1" +__version__ = "4.8.2" diff --git a/pyproject.toml b/pyproject.toml index 853d9ccaf8..b306e5e78c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "commitizen" -version = "4.8.1" +version = "4.8.2" description = "Python commitizen client tool" authors = [{ name = "Santiago Fraire", email = "santiwilly@gmail.com" }] maintainers = [ @@ -88,7 +88,7 @@ build-backend = "poetry.core.masonry.api" [tool.commitizen] -version = "4.8.1" +version = "4.8.2" tag_format = "v$version" version_files = [ "pyproject.toml:version", From 9420b44c86a9271d0d9f107360501a058533f9e2 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Fri, 23 May 2025 16:55:07 +0800 Subject: [PATCH 04/35] docs(label_pr.yml): add labels based on new PR title --- .github/workflows/label_pr.yml | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/.github/workflows/label_pr.yml b/.github/workflows/label_pr.yml index b409c8b757..176d7cc794 100644 --- a/.github/workflows/label_pr.yml +++ b/.github/workflows/label_pr.yml @@ -17,3 +17,31 @@ jobs: - uses: actions/labeler@v5 with: configuration-path: .github/labeler.yml + - name: Label based on PR title + uses: actions/github-script@v7 + with: + script: | + const title = context.payload.pull_request.title.toLowerCase(); + const labels = []; + + if (title.includes("fix") || title.includes("bug")) { + labels.push("type: bug"); + } + if (title.includes("feat")) { + labels.push("type: feature"); + } + if (title.includes("doc")) { + labels.push("type: documentation"); + } + if (title.includes("refactor")) { + labels.push("type: refactor"); + } + + if (labels.length > 0) { + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.pull_request.number, + labels + }); + } From 5aa58c6638f7e2237f596ec373e9001e21ba1a8c Mon Sep 17 00:00:00 2001 From: Adrian Carolli Date: Mon, 26 May 2025 19:45:10 -0400 Subject: [PATCH 05/35] docs: add installation and usage guide for cz-ai plugin leveraging GPT-4o --- docs/third-party-commitizen.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/third-party-commitizen.md b/docs/third-party-commitizen.md index 1c8ef8a183..b6d598985f 100644 --- a/docs/third-party-commitizen.md +++ b/docs/third-party-commitizen.md @@ -3,6 +3,22 @@ In addition to the native templates, some alternative commit format templates are available as PyPI packages (installable with `pip`). +### [cz-ai](https://github.com/watadarkstar/cz_ai) + +A Commitizen plugin that leverages OpenAI's GPT-4o to automatically generate clear, concise, and conventional commit messages based on your staged git changes. + +#### Installation + +```sh +pip install cz-ai +``` + +#### Usage + +```sh +cz --name cz_ai commit +``` + ### [Conventional JIRA](https://pypi.org/project/conventional-JIRA/) Just like _conventional commit_ format, but the scope has been restricted to a From e69e0a1babe6b9dd64f7c3cabb2246bd299379ab Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 17:04:41 +0800 Subject: [PATCH 06/35] 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 b6d598985f..e9eb822ed3 100644 --- a/docs/third-party-commitizen.md +++ b/docs/third-party-commitizen.md @@ -117,7 +117,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 c3d4152fb736969b83be7b555ea44b025ffc6c7e Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 17:19:32 +0800 Subject: [PATCH 07/35] 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 d08afc6706..f0df2f4242 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 23bd8936a448c15e36f775496221731fb40df0ad Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 22:53:40 +0800 Subject: [PATCH 08/35] 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 3fcefbd591aa1c14c40730d9deae82f7918f8b2a Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 23:08:34 +0800 Subject: [PATCH 09/35] 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 889198d5688e78793e4099e7493b030a652bb670 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 23:38:41 +0800 Subject: [PATCH 10/35] 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 36c7ae576fa4ffae3abcd16f95d5caf066fd7911 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 11 May 2025 23:55:40 +0800 Subject: [PATCH 11/35] 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 37a4a3ae4b0f9347f3cb4445931f027fee0ea9c2 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Mon, 12 May 2025 00:58:47 +0800 Subject: [PATCH 12/35] 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 f0df2f4242..cb834c5d6f 100644 --- a/commitizen/cli.py +++ b/commitizen/cli.py @@ -86,9 +86,8 @@ def __call__( data = { "prog": "cz", "description": ( - "Commitizen is a cli tool to generate conventional commits.\n" - "For more information about the topic go to " - "https://conventionalcommits.org/" + "Commitizen is a powerful release management tool that helps teams maintain consistent and meaningful commit messages while automating version management.\n" + "For more information, please visit https://commitizen-tools.github.io/commitizen" ), "formatter_class": argparse.RawDescriptionHelpFormatter, "arguments": [ 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 4cd6d78a6bfc603497f9cb2c1b14c38616218b9f Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Mon, 12 May 2025 01:56:29 +0800 Subject: [PATCH 13/35] 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 5e14843ef8ac0c85724588e0f49317132c3cab0f Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Mon, 12 May 2025 03:05:22 +0800 Subject: [PATCH 14/35] docs(pyproject.toml): fix typo --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index b306e5e78c..a653ecdb5d 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 614eaa3995cf45f55e8d1e7efdcf52e94946f2f8 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Tue, 13 May 2025 00:29:29 +0800 Subject: [PATCH 15/35] 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 f893d082030527dc965348ec6dfb163130b75359 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 14 May 2025 23:00:31 +0800 Subject: [PATCH 16/35] 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 6930aaaea170fba7fa1aca13cbff40b11d79564e Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 20:54:23 +0800 Subject: [PATCH 17/35] 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 ec57f7de0da977f43157b7235e7f817399bc10ed Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 21:13:54 +0800 Subject: [PATCH 18/35] 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 71c2e914d477ac7e45a05eddb9ad511f4fe0c4ca Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 21:22:04 +0800 Subject: [PATCH 19/35] 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 2a68e89aed582ef4d89c3d0799406f5cb6584c5a Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 21:27:41 +0800 Subject: [PATCH 20/35] 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 1c58b1c272c4ab9ee2ce93907280d5ac3bde10a6 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 21:44:23 +0800 Subject: [PATCH 21/35] 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 70af1a6dc947cb78d10de546d6441b89ccd5bcd8 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Thu, 15 May 2025 22:03:19 +0800 Subject: [PATCH 22/35] 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 e9eb822ed3..dc9b539c85 100644 --- a/docs/third-party-commitizen.md +++ b/docs/third-party-commitizen.md @@ -33,9 +33,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]. From f6280c88a14aabf30324a4d9901f4fee577debfc Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 18 May 2025 21:41:24 +0800 Subject: [PATCH 23/35] docs(README): update documentation site link text --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 9bb1555721..516b2a4863 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,7 +12,7 @@ --- -**Documentation:** [https://commitizen-tools.github.io/commitizen/](https://commitizen-tools.github.io/commitizen/) +[**Commitizen Documentation Site**](https://commitizen-tools.github.io/commitizen/) --- From ba1c9c0ce4cba699e61a2ab26d08d3159d0f3bdb Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 18 May 2025 21:46:08 +0800 Subject: [PATCH 24/35] docs(README): replace internal links with documentation site link --- docs/README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/README.md b/docs/README.md index 516b2a4863..078d6da06e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -42,11 +42,11 @@ This standardization makes your commit history more readable and meaningful, whi ### Features - Command-line utility to create commits with your rules. Defaults: [Conventional commits][conventional_commits] -- Bump version automatically using [semantic versioning][semver] based on the commits. [Read More](./commands/bump.md) +- Bump version automatically using [semantic versioning][semver] based on the commits. [Read More](https://commitizen-tools.github.io/commitizen/commands/bump/) - Generate a changelog using [Keep a changelog][keepchangelog] - Update your project's version files automatically - Display information about your commit rules (commands: schema, example, info) -- Create your own set of rules and publish them to pip. Read more on [Customization](./customization.md) +- Create your own set of rules and publish them to pip. Read more on [Customization](https://commitizen-tools.github.io/commitizen/customization/) ## Getting Started @@ -168,11 +168,11 @@ This command: - 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) +- [Version files](https://commitizen-tools.github.io/commitizen/commands/bump/#version_files) +- [Version scheme](https://commitizen-tools.github.io/commitizen/commands/bump/#version_scheme) +- [Version provider](https://commitizen-tools.github.io/commitizen/config/#version-providers) -For all available options, see the [bump command documentation](./commands/bump.md). +For all available options, see the [bump command documentation](https://commitizen-tools.github.io/commitizen/commands/bump/). ### Advanced Usage @@ -219,7 +219,7 @@ pre-commit install --hook-type commit-msg --hook-type pre-push > pre-commit autoupdate > ``` -For more details about commit validation, see the [check command documentation](commands/check.md). +For more details about commit validation, see the [check command documentation](https://commitizen-tools.github.io/commitizen/commands/check/). ## Help & Reference @@ -243,9 +243,9 @@ Commitizen provides a comprehensive CLI with various commands. Here's the comple ### Additional Resources - [Conventional Commits Specification][conventional_commits] -- [Exit Codes Reference](./exit_codes.md) -- [Configuration Guide](./config.md) -- [Command Documentation](./commands/init.md) +- [Exit Codes Reference](https://commitizen-tools.github.io/commitizen/exit_codes/) +- [Configuration Guide](https://commitizen-tools.github.io/commitizen/config/) +- [Command Documentation](https://commitizen-tools.github.io/commitizen/commands/init/) ### Getting Help @@ -257,7 +257,7 @@ cz bump --help cz changelog --help ``` -For more detailed documentation, visit our [documentation site](https://commitizen-tools.github.io/commitizen/). +For more details, visit our [documentation site](https://commitizen-tools.github.io/commitizen/). ## Setting up bash completion From bb1539deb206d58f7b94c3b8ece268f8f34f287d Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 18 May 2025 21:57:02 +0800 Subject: [PATCH 25/35] docs(README): paraphase features --- docs/README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/README.md b/docs/README.md index 078d6da06e..f730c17837 100644 --- a/docs/README.md +++ b/docs/README.md @@ -41,12 +41,13 @@ This standardization makes your commit history more readable and meaningful, whi ### Features -- Command-line utility to create commits with your rules. Defaults: [Conventional commits][conventional_commits] -- Bump version automatically using [semantic versioning][semver] based on the commits. [Read More](https://commitizen-tools.github.io/commitizen/commands/bump/) -- Generate a changelog using [Keep a changelog][keepchangelog] -- Update your project's version files automatically -- Display information about your commit rules (commands: schema, example, info) -- Create your own set of rules and publish them to pip. Read more on [Customization](https://commitizen-tools.github.io/commitizen/customization/) +- Interactive CLI for standardized commits with default [Conventional Commits][conventional_commits] support +- Intelligent [version bumping](https://commitizen-tools.github.io/commitizen/commands/bump/) using [Semantic Versioning][semver] +- Automatic [keep a changelog][keepchangelog] generation +- Built-in commit validation with pre-commit hooks +- [Customizable](https://commitizen-tools.github.io/commitizen/customization/) commit rules and templates +- Multi-format version file support +- Custom rules and plugins via pip ## Getting Started From 8e65b88288328dd794e9f8046f5b1164c9afb569 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 28 May 2025 01:27:30 +0000 Subject: [PATCH 26/35] docs(cli/screenshots): update CLI screenshots [skip ci] --- docs/images/cli_help/cz___help.svg | 172 +++++++++++++++-------------- 1 file changed, 88 insertions(+), 84 deletions(-) diff --git a/docs/images/cli_help/cz___help.svg b/docs/images/cli_help/cz___help.svg index 098e7df70d..d580cfe619 100644 --- a/docs/images/cli_help/cz___help.svg +++ b/docs/images/cli_help/cz___help.svg @@ -1,4 +1,4 @@ - + - - + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + - + - + - - $ 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/ - -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 rise error, -                        e.g: cz -nr 1,2,3 bump. See codes at -https://commitizen- -                        tools.github.io/commitizen/exit_codes/ - -commands: -{init,commit,c,ls,example,info,schema,bump,changelog,ch,check,version} -    init                init commitizen configuration -    commit (c)          create new commit -    ls                  show available commitizens -    example             show commit example -    info                show information about the cz -    schema              show commit schema -    bump                bump semantic version based on the git log -    changelog (ch)      generate changelog (note that it will overwrite -                        existing file) -    check               validates that a commit message matches the commitizen -                        schema -    version             get the version of the installed commitizen or the -                        current project (default: installed commitizen) - + + $ cz --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) + From aaa64aca07db9acd52ee069fc4abb572524e0cf4 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sat, 24 May 2025 00:56:51 +0800 Subject: [PATCH 27/35] docs(faq): add features we wont add Closes #1129 --- docs/faq.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/faq.md b/docs/faq.md index ceabac2e10..920f533d73 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,3 +1,11 @@ +## Features we won't add + +For a comprehensive list of features that have been considered but won't be implemented, please refer to our [issue tracker](https://github.com/commitizen-tools/commitizen/issues?q=is:issue%20state:closed%20label:%22issue-status:%20wont-fix%22%20OR%20label:%22issue-status:%20wont-implement%22). + +- Enable multiple locations of config file `.cz.*` [#955](https://github.com/commitizen-tools/commitizen/issues/955) +- Create a flag to build the changelog from commits in multiple git repositories [#790](https://github.com/commitizen-tools/commitizen/issues/790) +- Global Configuration [#597](https://github.com/commitizen-tools/commitizen/issues/597) + ## Support for PEP621 PEP621 establishes a `[project]` definition inside `pyproject.toml` From 3560156e518416846baec3cd7d3b772a7478ffb8 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sat, 24 May 2025 01:17:32 +0800 Subject: [PATCH 28/35] docs(bump): rewrite bump about section, fix incorrect version increment rules Closes #781 --- docs/commands/bump.md | 92 ++++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 32 deletions(-) diff --git a/docs/commands/bump.md b/docs/commands/bump.md index ee3d77430a..d399ec9eb8 100644 --- a/docs/commands/bump.md +++ b/docs/commands/bump.md @@ -2,51 +2,79 @@ ## About -`cz bump` **automatically** increases the version, based on the commits. +`cz bump` is a powerful command that **automatically** determines and increases your project's version number based on your commit history. It analyzes your commits to determine the appropriate version increment according to semantic versioning principles. -The commits should follow the rules established by the committer in order to be parsed correctly. +### Key Features -**prerelease** versions are supported (alpha, beta, release candidate). +- **Automatic Version Detection**: Analyzes commit history to determine the appropriate version bump +- **Manual Version Control**: Supports manual version specification when needed +- **Pre-release Support**: Handles alpha, beta, and release candidate versions +- **Multiple Version Schemes**: Supports both [PEP 0440][pep440] and [semantic versioning][semver] formats -The version can also be **manually** bumped. +### Version Increment Rules -The version format follows [PEP 0440][pep440] and [semantic versioning][semver]. - -This means `MAJOR.MINOR.PATCH` +The version follows the `MAJOR.MINOR.PATCH` format, with increments determined by your commit types: | Increment | Description | Conventional commit map | | --------- | --------------------------- | ----------------------- | -| `MAJOR` | Breaking changes introduced | `BREAKING CHANGE` | +| `MAJOR` | Breaking changes introduced | `BREAKING CHANGE`, bang (e.g. `feat!`)| | `MINOR` | New features | `feat` | -| `PATCH` | Fixes | `fix` + everything else | +| `PATCH` | Fixes and improvements | `fix`, `perf`, `refactor`| + +### Version Schemes -[PEP 0440][pep440] is the default, you can switch by using the setting `version_scheme` or the cli: +By default, Commitizen uses [PEP 0440][pep440] for version formatting. You can switch to semantic versioning using either: +1. Command line: ```sh cz bump --version-scheme semver ``` -Some examples of pep440: +2. Configuration file: +```toml +[tool.commitizen] +version_scheme = "semver" +``` -```bash -0.9.0 -0.9.1 -0.9.2 -0.9.10 -0.9.11 -1.0.0a0 # alpha -1.0.0a1 -1.0.0b0 # beta -1.0.0rc0 # release candidate -1.0.0rc1 -1.0.0 -1.0.1 -1.1.0 -2.0.0 -2.0.1a -``` - -`post` releases are not supported yet. +### PEP440 Version Examples + +Commitizen supports the [PEP 440][pep440] version format, which includes several version types. Here are examples of each: + +#### Standard Releases +```text +0.9.0 # Initial development release +0.9.1 # Patch release +0.9.2 # Another patch release +0.9.10 # Tenth patch release +0.9.11 # Eleventh patch release +1.0.0 # First stable release +1.0.1 # Patch release after stable +1.1.0 # Minor feature release +2.0.0 # Major version release +``` + +#### Pre-releases +```text +1.0.0a0 # Alpha release 0 +1.0.0a1 # Alpha release 1 +1.0.0b0 # Beta release 0 +1.0.0rc0 # Release candidate 0 +1.0.0rc1 # Release candidate 1 +``` + +#### Development Releases +```text +1.0.0.dev0 # Development release 0 +1.0.0.dev1 # Development release 1 +``` + +#### Combined Pre-release and Development +```text +1.0.0a1.dev0 # Development release 0 of alpha 1 +1.0.0b2.dev1 # Development release 1 of beta 2 +``` + +> **Note**: `post` releases (e.g., `1.0.0.post1`) are not currently supported. ## Usage @@ -97,7 +125,7 @@ by their precedence and showcase how a release might flow through a development By default, `--increment-mode` is set to `linear`, which ensures that bumping pre-releases _maintains linearity_: bumping of a pre-release with lower precedence than the current pre-release phase maintains the current phase of higher precedence. For example, if the current version is `1.0.0b1` then bumping with `--prerelease alpha` will -continue to bump the “beta” phase. +continue to bump the "beta" phase. Setting `--increment-mode` to `exact` instructs `cz bump` to instead apply the exact changes that have been specified with `--increment` or determined from the commit log. For example, @@ -223,7 +251,7 @@ If used together with a manual version the command also fails. We recommend setting `major_version_zero = true` in your configuration file while a project is in its initial development. Remove that configuration using a breaking-change commit to bump -your project’s major version to `v1.0.0` once your project has reached maturity. +your project's major version to `v1.0.0` once your project has reached maturity. ### `--version-scheme` From 08ced5dbfc6a3283be7cfac87afb86a652069622 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 28 May 2025 18:04:31 +0800 Subject: [PATCH 29/35] docs(README): fix broken bullet points --- docs/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/README.md b/docs/README.md index f730c17837..31f2a77d15 100644 --- a/docs/README.md +++ b/docs/README.md @@ -163,12 +163,14 @@ cz bump ``` This command: + - Bumps your project's version - Creates a git tag - Updates the changelog (if `update_changelog_on_bump` is enabled) - Updates version files You can customize: + - [Version files](https://commitizen-tools.github.io/commitizen/commands/bump/#version_files) - [Version scheme](https://commitizen-tools.github.io/commitizen/commands/bump/#version_scheme) - [Version provider](https://commitizen-tools.github.io/commitizen/config/#version-providers) @@ -187,6 +189,7 @@ 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 From 59e7532cccabf08a0a4b633a13ee174853f5c6f0 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 28 May 2025 18:31:53 +0800 Subject: [PATCH 30/35] docs(external_links): typo --- docs/external_links.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/external_links.md b/docs/external_links.md index 24e4127d86..a90bbd085b 100644 --- a/docs/external_links.md +++ b/docs/external_links.md @@ -4,7 +4,7 @@ | Name | Speaker | Occasion | Language | Extra | | ------------------------------------------------------------------------- | --------------- | ---------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | -| commitizen-tools: What can we gain from crafting a git message convention | Wei Lee | Taipey.py 2020 June Meetup, Remote Python Pizza 2020 | English | [slides](https://speakerdeck.com/leew/commitizen-tools-what-can-we-gain-from-crafting-a-git-message-convention-at-taipey-dot-py) | +| commitizen-tools: What can we gain from crafting a git message convention | Wei Lee | Taipei.py 2020 June Meetup, Remote Python Pizza 2020 | English | [slides](https://speakerdeck.com/leew/commitizen-tools-what-can-we-gain-from-crafting-a-git-message-convention-at-taipey-dot-py) | | Automating release cycles | Santiago Fraire | PyAmsterdam June 24, 2020, Online | English | [slides](https://woile.github.io/commitizen-presentation/) | | [Automatizando Releases con Commitizen y Github Actions][automatizando] | Santiago Fraire | PyConAr 2020, Remote | Español | [slides](https://woile.github.io/automating-releases-github-actions-presentation/#/) | From 739abd50a12f996144fc73a5f5dc0fa668b252dc Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 28 May 2025 17:52:14 +0800 Subject: [PATCH 31/35] docs(init): rewrite commands init page --- docs/commands/init.md | 67 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 53 insertions(+), 14 deletions(-) diff --git a/docs/commands/init.md b/docs/commands/init.md index a799c44810..4d92112d34 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -1,27 +1,66 @@ +The `cz init` command helps you set up Commitizen in your project by creating a configuration file with your preferred settings. + ## Usage ![cz init --help](../images/cli_help/cz_init___help.svg) -## Example - -To start using Commitizen, the recommended approach is to run +## Command ```sh cz init ``` +## Interactive Configuration + +When you run `cz init`, Commitizen will guide you through an interactive setup process: + ![init](../images/init.gif) -This command will ask you for information about the project and will -configure the selected file type (`pyproject.toml`, `.cz.toml`, etc.). +## Configuration File + +The initialization process will create a configuration file in your project root. + +Choose the configuration file format based on your project type: + +- Use `pyproject.toml` for Python projects +- Use `.cz.toml`, `.cz.yaml`, `.cz.json`, etc. for other projects. + +## Configuration Options + +During the initialization process, you'll be prompted to configure the following settings: + +1. **Convention Rules**: Select the commit message convention to follow (e.g., conventional commits) +2. **Version Provider**: Choose how to manage versioning in your project. Commitizen supports multiple version management systems: + - `commitizen`: Uses Commitizen's built-in version management system + - `npm`: Manages version in `package.json` for Node.js projects + - `cargo`: Manages version in `Cargo.toml` for Rust projects + - `composer`: Manages version in `composer.json` for PHP projects + - `pep621`: Uses `pyproject.toml` with PEP 621 standard + - `poetry`: Uses `pyproject.toml` with Poetry configuration + - `uv`: Uses `pyproject.toml` and `uv.lock` for Python projects + - `scm`: Reads version directly from git tags without modifying files +3. **Project Version**: The current version of your project will be detected automatically +4. **Tag Format**: The format used for version tags in your repository +5. **Version Type**: Choose between: + - `semver` or `semver2`: Semantic Versioning (MAJOR.MINOR.PATCH) + - `pep440`: Python Package Versioning +6. **Changelog Generation**: Configure whether to automatically generate changelog during version bumps +7. **Alpha Versioning**: Option to keep major version at 0 for alpha/beta software +8. **Pre-commit Hooks**: Set up Git pre-commit hooks for automated commit message validation + +## Example + +```sh +# Start the initialization process +cz init + +# Follow the interactive prompts to configure your project +``` + +## Next Steps -The `init` will help you with +After initialization, you can: -1. Choose a convention rules (`name`) -2. Choosing a version provider (`commitizen` or for example `Cargo.toml`) -3. Detecting your project's version -4. Detecting the tag format used -5. Choosing a version type (`semver` or `pep440`) -6. Whether to create the changelog automatically or not during bump -7. Whether you want to keep the major as zero while building alpha software. -8. Whether to setup pre-commit hooks. +1. Start using `cz commit` to create conventional commits +2. Use `cz bump` to manage versioning +3. Configure additional settings in your project's configuration file From ceb2b7afef13b48a1fe978de3e4cbba472fb6609 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 28 May 2025 18:25:30 +0800 Subject: [PATCH 32/35] docs: correct case GitHub --- docs/commands/bump.md | 2 +- docs/tutorials/github_actions.md | 2 +- mkdocs.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/commands/bump.md b/docs/commands/bump.md index d399ec9eb8..8219cc3461 100644 --- a/docs/commands/bump.md +++ b/docs/commands/bump.md @@ -219,7 +219,7 @@ understand that the user wants to create a changelog. It is recommended to be explicit and use `--changelog` (or the setting `update_changelog_on_bump`). This command is useful to "transport" the newly created changelog. -It can be sent to an auditing system, or to create a Github Release. +It can be sent to an auditing system, or to create a GitHub Release. Example: diff --git a/docs/tutorials/github_actions.md b/docs/tutorials/github_actions.md index bf08eb3bc5..2cb58cfee6 100644 --- a/docs/tutorials/github_actions.md +++ b/docs/tutorials/github_actions.md @@ -1,4 +1,4 @@ -## Create a new release with Github Actions +## Create a new release with GitHub Actions ### Automatic bumping of version diff --git a/mkdocs.yml b/mkdocs.yml index a8a2fe2d44..7b1e0feb30 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,7 +50,7 @@ nav: - Auto check commits: "tutorials/auto_check.md" - Auto prepare commit message: "tutorials/auto_prepare_commit_message.md" - GitLab CI: "tutorials/gitlab_ci.md" - - Github Actions: "tutorials/github_actions.md" + - GitHub Actions: "tutorials/github_actions.md" - Jenkins pipeline: "tutorials/jenkins_pipeline.md" - Developmental releases: "tutorials/dev_releases.md" - Monorepo support: "tutorials/monorepo_guidance.md" From 4b6b3fb4f9782ed0d55db5518b1e1523e0779eea Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 28 May 2025 18:16:16 +0800 Subject: [PATCH 33/35] docs(commit): rewrite command commit page --- docs/commands/commit.md | 75 ++++++++++++++++++++++++----------------- 1 file changed, 44 insertions(+), 31 deletions(-) diff --git a/docs/commands/commit.md b/docs/commands/commit.md index febaee3cf2..5a073a2644 100644 --- a/docs/commands/commit.md +++ b/docs/commands/commit.md @@ -1,52 +1,65 @@ +## Usage + +![cz commit --help](../images/cli_help/cz_commit___help.svg) + +## Overview + ![Using Commitizen cli](../images/demo.gif) -## About +The `commit` command provides an interactive way to create structured commits. Use either: -In your terminal run `cz commit` or the shortcut `cz c` to generate a guided git commit. +- `cz commit` +- `cz c` (shortcut) -You can run `cz commit --write-message-to-file COMMIT_MSG_FILE` to additionally save the -generated message to a file. This can be combined with the `--dry-run` flag to only -write the message to a file and not modify files and create a commit. A possible use -case for this is to [automatically prepare a commit message](../tutorials/auto_prepare_commit_message.md). +By default, Commitizen uses conventional commits, but you can customize the commit rules to match your project's needs. See the [customization guide](../customization.md) for details. +## Basic Usage -!!! note - To maintain platform compatibility, the `commit` command disable ANSI escaping in its output. - In particular pre-commit hooks coloring will be deactivated as discussed in [commitizen-tools/commitizen#417](https://github.com/commitizen-tools/commitizen/issues/417). +### Interactive Commit Creation -## Usage +Simply run `cz commit` in your terminal to start the interactive commit creation process. The command will guide you through creating a properly formatted commit message according to your configured rules. -![cz commit --help](../images/cli_help/cz_commit___help.svg) +### Writing Messages to File -### git options +You can save the generated commit message to a file using: +```sh +cz commit --write-message-to-file COMMIT_MSG_FILE +``` -`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: +This can be combined with `--dry-run` to only write the message without creating a commit. This is particularly useful for [automatically preparing commit messages](../tutorials/auto_prepare_commit_message.md). + +## Advanced Features + +### Git Command Options + +You can pass any git commit options using the `--` syntax: ```sh cz commit -- -# e.g., cz commit --dry-run -- -a -S +# Examples: +cz c --dry-run -- -a -S # Stage all changes and sign the commit +cz c -a -- -n # Stage all changes and skip the pre-commit and commit-msg hooks ``` -For example, using the `-S` option on `git commit` to sign a commit is now Commitizen compatible: `cz c -- -S` -!!! note - Deprecation warning: A commit can be signed off using `cz commit --signoff` or the shortcut `cz commit -s`. - This syntax is now deprecated in favor of the new `cz commit -- -s` syntax. +!!! warning + The `--signoff` option (or `-s`) is now recommended being used with the new syntax: `cz commit -- -s`. The old syntax `cz commit --signoff` is deprecated. ### Retry -You can use `cz commit --retry` to reuse the last commit message when the previous commit attempt failed. -To automatically retry when running `cz commit`, you can set the `retry_after_failure` -configuration option to `true`. Running `cz commit --no-retry` makes Commitizen ignore `retry_after_failure`, forcing -a new commit message to be prompted. +- Use `cz commit --retry` to reuse the last commit message after a failed commit attempt +- Set `retry_after_failure: true` in your configuration to automatically retry +- Use `cz commit --no-retry` to force a new commit message prompt + +### Message Length Control -### Commit message length limit +Control the length of your commit messages using the `-l` or `--message-length-limit` option: +```sh +cz commit -l 72 # Limits message length to 72 characters +``` + +!!! note + The length limit only applies to the first line of the commit message. For conventional commits, this means the limit applies from the type of change through the subject. The body and footer are not counted. -The argument `-l` (or `--message-length-limit`) followed by a positive number can limit the length of commit messages. -An exception would be raised when the message length exceeds the limit. -For example, `cz commit -l 72` will limit the length of commit messages to 72 characters. -By default, the limit is set to 0, which means no limit on the length. +## Technical Notes -**Note that the limit applies only to the first line of the message.** -Specifically, for `ConventionalCommitsCz` the length only counts from the type of change to the subject, -while the body and the footer are not counted. +For platform compatibility, the `commit` command disables ANSI escaping in its output. This means pre-commit hooks coloring will be deactivated as discussed in [commitizen-tools/commitizen#417](https://github.com/commitizen-tools/commitizen/issues/417). From 13e4aaacbde5bcfc4bd2aea1a1c060508b86dcec Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 1 Jun 2025 14:03:53 +0800 Subject: [PATCH 34/35] docs(contributing): improve documentation for first-time contributors --- docs/contributing.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index e9e162d2df..8389e9370d 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,10 +1,14 @@ -## Contributing to commitizen +## Contributing to Commitizen -First, thank you for taking the time to contribute! 🎉 +First, thank you for taking the time to contribute! 🎉 Your contributions help make Commitizen better for everyone. -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. +When contributing to Commitizen, we encourage you to: -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. +1. First, check out the [issues](https://github.com/commitizen-tools/commitizen/issues) and [Features we won't add](faq.md#features-we-wont-add) to see if there's already a discussion about the change you wish to make. +2. If there's no discussion, [create an issue](https://github.com/commitizen-tools/commitizen/issues/new) to discuss your proposed changes. +3. Follow our [development workflow](#development-workflow) and guidelines below. + +If you're a first-time contributor, please check out issues labeled [good first issue](https://github.com/commitizen-tools/commitizen/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - these are specifically chosen to be beginner-friendly. ## Prerequisites & Setup From 47beadc563d8272b64f88ddbf3e9a37351b8f535 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Sun, 1 Jun 2025 14:15:29 +0800 Subject: [PATCH 35/35] docs(pull_request_template): add task to fix broken external links in the docs --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5686474709..e37148c0a1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -25,7 +25,7 @@ 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 +- [ ] Check and fix any broken links (internal or external) in the documentation > When running `poetry doc`, any broken internal documentation links will be reported in the console output like this: >