Merge branch 'master' into docs-faq

Author: bearomorphism

.github/workflows/bumpversion.yml

@@ -12,7 +12,7 @@ jobs:
     name: "Bump version and create changelog with commitizen"
     steps:
       - name: Check out
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"

.github/workflows/docspublish.yml

@@ -10,7 +10,7 @@ jobs:
   update-cli-screenshots:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
           fetch-depth: 0
@@ -43,7 +43,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: update-cli-screenshots
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
           fetch-depth: 0

.github/workflows/homebrewpublish.yml

@@ -12,7 +12,7 @@ jobs:
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
@@ -24,7 +24,7 @@ jobs:
         run: |
           echo "project_version=$(cz version --project)" >> $GITHUB_ENV
       - name: Update Homebrew formula
-        uses: dawidd6/action-homebrew-bump-formula@v5
+        uses: dawidd6/action-homebrew-bump-formula@v6
         with:
           token: ${{secrets.PERSONAL_ACCESS_TOKEN}}
           formula: commitizen

.github/workflows/label_pr.yml

@@ -9,7 +9,7 @@ jobs:
       pull-requests: write
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
       with:
         sparse-checkout: |
           .github/labeler.yml

.github/workflows/pythonpackage.yml

@@ -10,7 +10,7 @@ jobs:
         platform: [ubuntu-22.04, macos-latest, windows-latest]
     runs-on: ${{ matrix.platform }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Set up Python ${{ matrix.python-version }}

.github/workflows/pythonpublish.yml

@@ -9,7 +9,7 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
           fetch-depth: 0

docs/commands/bump.md

@@ -111,7 +111,7 @@ Commitizen supports the [PEP 440][pep440] version format, which includes several
 
 ### `--files-only`
 
-Bumps the version in the files defined in [`version_files`](#version_files) without creating a commit and tag on the git repository,
+Bumps the version in the files defined in [`version_files`](#version_files) without creating a commit and tag on the git repository.
 
 ```bash
 cz bump --files-only
@@ -128,7 +128,7 @@ cz bump --changelog
 ### `--prerelease`
 
 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
+pre-release segment compatible with the bump's version scheme, where the segment consists of a _phase_ and a
 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).
@@ -222,10 +222,11 @@ In this example, it will detect that `setup.py` contains `1.0.5` instead of `1.2
       ```
 
     2. Manually update the version in `setup.py` to match the version in `pyproject.toml`:
-      ```python title="setup.py"
+      ```diff title="setup.py"
       from setuptools import setup
 
-      setup(..., version="1.21.0", ...)
+      - setup(..., version="1.0.5", ...)
+      + setup(..., version="1.21.0", ...)
       ```
 
     3. Run the bump command again:
@@ -280,19 +281,20 @@ Any other messages generated by `cz bump` will be sent to `stderr`.
 When this flag is used, `--changelog` is implied.
 However, it is recommended to set `--changelog` (or the setting `update_changelog_on_bump`) explicitly when the option `--changelog-to-stdout` is used.
 
-#### Useful scenarios
+!!! note "Useful scenarios"
+    Pipe the newly created changelog to another tool.
 
-This is useful to pipe the newly created changelog to another tool. For example, it can be sent to an auditing system, or to create a GitHub Release, etc.
+    The output can be redirected to an auditing system, or used to create a GitHub Release, etc.
 
-```bash
-cz bump --changelog --changelog-to-stdout > body.md
-```
+    ```bash
+    cz bump --changelog --changelog-to-stdout > body.md
+    ```
 
 ### `--git-output-to-stderr`
 
-If `--git-output-to-stderr` is used, git commands output is redirected to `stderr`.
+Redirects git commands output to `stderr`.
 
-Useful when used with `--changelog-to-stdout` and piping the output to a file,
+Useful when used with `--changelog-to-stdout` and piping the output to a file.
 
 For example, `git commit` output may pollute `stdout`, so it is recommended to use this flag when piping the output to a file.
 
@@ -305,7 +307,7 @@ Useful to combine with code formatters, like [Prettier](https://prettier.io/).
 
 ### `--major-version-zero`
 
-Breaking changes does not bump the major version number.
+Breaking changes do not bump the major version number.
 
 Say you have a project with the version `0.1.x` and you commit a breaking change like this:
 
@@ -343,7 +345,7 @@ Then the version of your project will be bumped to `0.2.0` instead of `1.0.0`.
 
 ### `--gpg-sign`
 
-Create gpg signed tags.
+Creates gpg signed tags.
 
 ```bash
 cz bump --gpg-sign
@@ -366,18 +368,16 @@ See [the template customization section](../customization.md#customizing-the-cha
 
 ### `--build-metadata`
 
-Provides a way to specify additional metadata in the version string. This parameter is not compatible with `--local-version` as it uses the same part of the version string.
+Specifies additional metadata in the version string.
 
 ```bash
+# creates a version like `1.1.2+yourmetadata`.
 cz bump --build-metadata yourmetadata
 ```
 
-Will create a version like `1.1.2+yourmetadata`.
-
-This can be useful for multiple things
-
-- Git hash in version
-- Labeling the version with additional metadata.
+!!! note "Example usage"
+    - Git hash in version
+    - Labeling the version with additional metadata.
 
 !!! note
     Commitizen ignores everything after `+` when it bumps the version.
@@ -391,16 +391,19 @@ This can be useful for multiple things
     - Version `1.2.3+a`, and `1.2.3+b` are the same version! Tools should not use the string after `+` for version calculation. This is probably not a guarantee (example in helm) even tho it is in the spec.
     - It might be problematic having the metadata in place when doing upgrades depending on what tool you use.
 
+!!! warning
+    This parameter is not compatible with `--local-version` as it uses the same part of the version string.
+
 ### `--get-next`
 
-Provides a way to determine the next version and write it to stdout. This parameter is not compatible with `--changelog`
-and `manual version`.
+Similar to `--dry-run` but only outputs the next version.
 
 ```bash
+# outputs 1.0.1 if the current version is 1.0.0 and the increment is PATCH
 cz bump --get-next
 ```
 
-Will only output the next version, e.g., `1.2.3`. This can be useful for determining the next version based on CI for non-production environments/builds.
+Useful for determining the next version based on CI for non-production environments/builds.
 
 !!! note "Compare with `--dry-run`"
     `--dry-run` provides a more detailed output including the changes as they would appear in the changelog file, while `--get-next` only outputs the next version.
@@ -426,15 +429,27 @@ Will only output the next version, e.g., `1.2.3`. This can be useful for determi
 
 ### `--allow-no-commit`
 
-Allow the project version to be bumped even when there's no eligible version. This is most useful when used with `--increment {MAJOR,MINOR,PATCH}` or `[MANUAL_VERSION]`
+Allow the project version to be bumped even when there's no eligible version.
 
-```sh
-# bump a minor version even when there's only bug fixes, documentation changes or even no commits
-cz bump --incremental MINOR --allow-no-commit
+!!! note "Example usage"
+    ```sh
+    # bump a minor version even when there's only bug fixes, documentation changes or even no commits
 
-# bump version to 2.0.0 even when there's no breaking changes changes or even no commits
-cz bump --allow-no-commit 2.0.0
-```
+    cz bump --increment MINOR --allow-no-commit
+
+    # bump version to 2.0.0 even when there's no breaking changes or even no commits
+    cz bump --allow-no-commit 2.0.0
+    ```
+
+!!! note "Default increment"
+    The increment is overridden to `PATCH` if there is no increment detected or specified.
+
+    In other words, `cz bump --allow-no-commit` allows you to bump the version to the next patch version even when there is no eligible commit.
+
+    ```sh
+    # will bump to `1.0.1` if the current version is `1.0.0`.
+    cz bump --allow-no-commit
+    ```
 
 ### `--version-scheme`
 
@@ -479,19 +494,19 @@ Supported variables:
 
 | Variable                       | Description                                 |
 |--------------------------------|---------------------------------------------|
-| `$version`, `${version}`       | fully generated version                      |
+| `$version`, `${version}`       | fully generated version                     |
 | `$major`, `${major}`           | MAJOR increment                             |
 | `$minor`, `${minor}`           | MINOR increment                             |
 | `$patch`, `${patch}`           | PATCH increment                             |
 | `$prerelease`, `${prerelease}` | Prerelease (alpha, beta, release candidate) |
-| `$devrelease`, ${devrelease}`  | Development release                         |
+| `$devrelease`, `${devrelease}` | Development release                         |
 
 ### `version_files`
 
 Identify the files or glob patterns which should be updated with the new version.
 
 Commitizen will update its configuration file automatically when bumping,
-regarding if the file is present or not in `version_files`.
+regardless of whether the file is present or not in `version_files`.
 
 You may specify the `version_files` in your configuration file.
 
@@ -685,7 +700,7 @@ See [Version Schemes](#version-schemes-version-scheme).
 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
+If you have a special use case, where you don't want to raise one of these error codes, you can
 tell Commitizen to not raise them.
 
 ### Recommended use case

docs/customization.md

@@ -207,7 +207,7 @@ cookiecutter gh:commitizen-tools/commitizen_cz_template
 
 See [commitizen_cz_template](https://github.com/commitizen-tools/commitizen_cz_template) for details.
 
-Once you publish your rules, you can send us a PR to the [Third-party section](./third-party-commitizen.md).
+Once you publish your rules, you can send us a PR to the [Third-party section](./third-party-plugins/about.md).
 
 ### Custom commit rules
 

docs/external_links.md

@@ -3,14 +3,15 @@
 ## Talks
 
 | Name                                                                      | Speaker         | Occasion                                             | Language | Extra                                                                                                                            |
-| ------------------------------------------------------------------------- | --------------- | ---------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| 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/#/)                                             |
+| ------------------------------------------------------------------------- | --------------- | ---------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| [Atomic Commits: An Easy & Proven Way to Manage & Automate Release Process](https://www.youtube.com/watch?v=IxzN9ClXhs8) | Wei Lee         | COSCUP 2023                                          | Taiwanese Mandarin | [slides](https://speakerdeck.com/leew/atomic-commits-an-easy-and-proven-way-to-manage-and-automate-release-process) |
+| 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/#/)                                             |
 
 ## Articles
 
-- [Python Table Manners - Commitizen: 規格化 commit message](https://lee-w.github.io/posts/tech/2020/03/python-table-manners-commitizen/) (Written in Traditional Mandarin)
+- [Python Table Manners - Commitizen: 規格化 commit message](https://blog.wei-lee.me/posts/tech/2020/03/python-table-manners-commitizen/) (Written in Traditional Mandarin)
 - [Automating semantic release with commitizen](https://woile.dev/posts/automating-semver-releases-with-commitizen/) (English)
 - [How to Write Better Git Commit Messages – A Step-By-Step Guide](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/?utm_source=tldrnewsletter) (English)
 - [Continuous delivery made easy (in Python)](https://medium.com/dev-genius/continuous-delivery-made-easy-in-python-c085e9c82e69)