Merge branch 'master' into doc-config

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@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"

.github/workflows/docspublish.yml

@@ -4,12 +4,13 @@ on:
   push:
     branches:
       - master
+  workflow_dispatch:
 
 jobs:
   update-cli-screenshots:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
           fetch-depth: 0
@@ -42,7 +43,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: update-cli-screenshots
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
           fetch-depth: 0
@@ -58,21 +59,19 @@ jobs:
           python -m pip install -U pip poetry poethepoet
           poetry --version
           poetry install --no-root --only documentation
-      - name: Build docs
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          poetry doc:build
       - name: Generate Sponsors 💖
         uses: JamesIves/github-sponsors-readme-action@v1
         with:
           token: ${{ secrets.PERSONAL_ACCESS_TOKEN_FOR_ORG }}
           file: "docs/README.md"
-      - name: Push doc to Github Page
-        uses: peaceiris/actions-gh-pages@v4
+          organization: true
+      - name: Build docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          poetry doc:build
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
-          personal_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-          publish_branch: gh-pages
-          publish_dir: ./site
-          user_name: "github-actions[bot]"
-          user_email: "github-actions[bot]@users.noreply.github.com"
+          folder: ./site # The folder the action should deploy.
+          branch: gh-pages

.github/workflows/homebrewpublish.yml

@@ -12,7 +12,7 @@ jobs:
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
       - name: Set up Python
         uses: actions/setup-python@v5
         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@v4
+        uses: dawidd6/action-homebrew-bump-formula@v5
         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@v4
+    - uses: actions/checkout@v5
       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@v4
+      - uses: actions/checkout@v5
         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@v4
+      - uses: actions/checkout@v5
         with:
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
           fetch-depth: 0

docs/README.md

@@ -63,6 +63,7 @@ Before installing Commitizen, ensure you have:
 #### Global Installation (Recommended)
 
 The recommended way to install Commitizen is using [`pipx`](https://pipx.pypa.io/) or [`uv`](https://docs.astral.sh/uv/), which ensures a clean, isolated installation:
+
 **Using pipx:**
 ```bash
 # Install Commitizen
@@ -111,7 +112,7 @@ poetry add commitizen --dev
 
 **Using uv:**
 ```bash
-uv add commitizen
+uv add --dev commitizen
 ```
 
 **Using pdm:**

docs/commands/bump.md

@@ -31,7 +31,7 @@ cz bump --version-scheme semver
 ```
 
 2. Configuration file:
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version_scheme = "semver"
 ```
@@ -113,7 +113,7 @@ Note that as per [semantic versioning spec](https://semver.org/#spec-item-9)
 For example, the following versions (using the [PEP 440](https://peps.python.org/pep-0440/) scheme) are ordered
 by their precedence and showcase how a release might flow through a development cycle:
 
-- `1.0.0` is the current published version
+- `1.0.0` is the currently published version
 - `1.0.1a0` after committing a `fix:` for pre-release
 - `1.1.0a1` after committing an additional `feat:` for pre-release
 - `1.1.0b0` after bumping a beta release
@@ -153,7 +153,7 @@ cz bump --check-consistency
 
 For example, if we have `pyproject.toml`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version = "1.21.0"
 version_files = [
@@ -162,15 +162,16 @@ version_files = [
 ]
 ```
 
-`src/__version__.py`,
+`src/__version__.py`
 
-```python
+
+```python title="src/__version__.py"
 __version__ = "1.21.0"
 ```
 
-and `setup.py`.
+and `setup.py`
 
-```python
+```python title="setup.py"
 from setuptools import setup
 
 setup(..., version="1.0.5", ...)
@@ -193,7 +194,7 @@ cz bump --local-version
 
 For example, if we have `pyproject.toml`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version = "5.3.5+0.1.0"
 ```
@@ -454,7 +455,7 @@ In your `pyproject.toml` or `.cz.toml`
 tag_format = "v$major.$minor.$patch$prerelease"
 ```
 
-The variables must be preceded by a `$` sign and optionally can be wrapped in `{}` . Default is `$version`.
+The variables must be preceded by a `$` sign and optionally can be wrapped in `{}`. The default is `$version`.
 
 Supported variables:
 
@@ -471,7 +472,7 @@ Supported variables:
 
 ### `version_files` \*
 
-It is used to identify the files which should be updated with the new version.
+It is used to identify the files or glob patterns which should be updated with the new version.
 It is also possible to provide a pattern for each file, separated by colons (`:`).
 
 Commitizen will update its configuration file automatically (`pyproject.toml`, `.cz`) when bumping,
@@ -483,11 +484,12 @@ Some examples
 
 `pyproject.toml`, `.cz.toml` or `cz.toml`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version_files = [
     "src/__version__.py",
-    "setup.py:version"
+    "packages/*/pyproject.toml:version",
+    "setup.py:version",
 ]
 ```
 
@@ -496,8 +498,7 @@ This means that it will find a file `setup.py` and will only make a change
 in a line containing the `version` substring.
 
 !!! note
-    Files can be specified using relative (to the execution) paths, absolute paths
-    or glob patterns.
+    Files can be specified using relative (to the execution) paths, absolute paths, or glob patterns.
 
 ---
 
@@ -516,7 +517,7 @@ Some examples
 
 `pyproject.toml`, `.cz.toml` or `cz.toml`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 bump_message = "release $current_version → $new_version [skip-ci]"
 ```
@@ -529,7 +530,7 @@ When set to `true` the changelog is always updated incrementally when running `c
 
 Defaults to: `false`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 update_changelog_on_bump = true
 ```
@@ -540,7 +541,7 @@ update_changelog_on_bump = true
 
 When set to `true`, Commitizen will create annotated tags.
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 annotated_tag = true
 ```
@@ -551,7 +552,7 @@ annotated_tag = true
 
 When set to `true`, Commitizen will create gpg signed tags.
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 gpg_sign = true
 ```
@@ -565,7 +566,7 @@ Useful during the initial development stage of your project.
 
 Defaults to: `false`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 major_version_zero = true
 ```
@@ -591,7 +592,7 @@ execution of the script, some environment variables are available:
 | `CZ_PRE_INCREMENT`           | Whether this is a `MAJOR`, `MINOR` or `PATH` release       |
 | `CZ_PRE_CHANGELOG_FILE_NAME` | Path to the changelog file, if available                   |
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 pre_bump_hooks = [
   "scripts/generate_documentation.sh"
@@ -618,7 +619,7 @@ release. During execution of the script, some environment variables are availabl
 | `CZ_POST_INCREMENT`            | Whether this was a `MAJOR`, `MINOR` or `PATH` release      |
 | `CZ_POST_CHANGELOG_FILE_NAME`  | Path to the changelog file, if available                    |
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 post_bump_hooks = [
   "scripts/slack_notification.sh"
@@ -631,7 +632,7 @@ Offset with which to start counting prereleases.
 
 Defaults to: `0`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 prerelease_offset = 1
 ```
@@ -651,7 +652,7 @@ Options: `pep440`, `semver`, `semver2`
 
 Defaults to: `pep440`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version_scheme = "semver"
 ```

docs/config.md

@@ -21,7 +21,7 @@ Current version. Example: `"0.1.2"`. Required if you use `version_provider = "co
 - Type: `list`
 - Default: `[]`
 
-Files were the version will be updated. A pattern to match a line, can also be specified, separated by `:`. [Read more][version_files]
+Files (or glob patterns) where the version will be updated. A pattern to match a line, can also be specified, separated by `:` [Read more][version_files]
 
 ### `version_provider`
 

docs/third-party-commitizen.md

@@ -145,3 +145,56 @@ commitizen:
   version_provider: deno-provider
   version_scheme: semver
 ```
+
+### [cz-path](https://pypi.org/project/cz-path/)
+
+Provides prefix choices for commit messages based on staged files (Git only).
+For example, if the staged files are `component/z/a.ts` and `component/z/b.ts`,
+the path prefix option will be `component/z` and commit message might look like:
+`component/z/: description of changes`. If only one file is staged, the extension
+is removed in the prefix.
+
+#### Installation
+
+```sh
+pip install cz-path
+```
+
+#### Usage
+
+Add `cz-path` to your configuration file.
+
+Example for `.cz.json`:
+
+```json
+{
+  "commitizen": {
+    "name": "cz_path",
+    "remove_path_prefixes": ["src", "module_name"]
+  }
+}
+```
+
+The default value for `remove_path_prefixes` is `["src"]`. Adding `/` to the
+prefixes is not required.
+
+#### Example session
+
+```plain
+ $ git add .vscode/
+ $ cz -n cz_path c
+? Prefix: (Use arrow keys)
+ » .vscode
+   .vscode/
+   project
+   (empty)
+? Prefix: .vscode
+? Commit title: adjust settings
+
+.vscode: adjust settings
+
+[main 0000000] .vscode: adjust settings
+ 2 files changed, 1 insertion(+), 11 deletions(-)
+
+Commit successful!
+```