Merge branch 'master' into feat/support-for-pep-751

Author: josix

.agents/skills/commitizen/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: commitizen
+description: Use this skill for tasks involving Conventional Commits, commit message validation, Commitizen configuration, semantic version bumps, changelog generation, or CI/release automation with the Commitizen CLI.
+license: MIT
+compatibility: Git repository with Python and Commitizen available as `cz` or runnable from source. Network access is optional and mainly relevant for CI or release integrations.
+metadata:
+  project: commitizen-tools/commitizen
+  docs: https://commitizen-tools.github.io/commitizen/
+  install: "pip install commitizen"
+---
+
+# Commitizen
+
+Commitizen is a CLI for enforcing Conventional Commits, automating version bumps, and generating changelogs.
+
+## Use this skill when
+
+- A task involves commit message authoring or validation.
+- A repository needs Commitizen initialization or configuration updates.
+- Work depends on version schemes, version providers, version files, tags, or changelog behavior.
+- CI/CD automation needs commit validation, automated version bumps, or release notes.
+
+## Core workflow
+
+1. Find the active configuration file in this order: `.cz.toml`, `cz.toml`, `.cz.json`, `cz.json`, `.cz.yaml`, `cz.yaml`, then `pyproject.toml` under `[tool.commitizen]`.
+2. Read the effective settings before acting, especially `name`, `version`, `version_provider`, `version_scheme`, `version_files`, `tag_format`, `update_changelog_on_bump`, `annotated_tag`, `bump_message`, `pre_bump_hooks`, and `post_bump_hooks`.
+3. Match the command to the task:
+   - `cz commit` for interactive commit authoring
+   - `cz check` for validating commit messages or git ranges
+   - `cz init` for bootstrapping configuration
+   - `cz bump` for calculating or applying release versions
+   - `cz changelog` for generating or updating `CHANGELOG.md`
+   - `cz ls` for listing available commit rules
+   - `cz version` for showing the current version
+4. Prefer read-only inspection first. Safe discovery commands include `cz version`, `cz ls`, `cz check`, `cz bump --get-next`, and `cz bump --dry-run`.
+5. Treat `cz bump` as stateful: it can update version files, create a bump commit, and create a git tag. Verify the version provider, version scheme, tag format, and changelog settings before running it for real.
+6. When automating in CI, check whether the workflow should ignore specific exit codes with `--no-raise` and whether `bump_message` should include skip-CI text.
+7. After making changes, validate the resulting configuration, commands, and automation against the repository's actual version scheme and provider.
+
+## Important domain details
+
+- Commitizen installs with `pip install commitizen` or `uv add commitizen`.
+- The default version scheme is PEP 440; `semver` and `semver2` are also supported.
+- Common version providers include `commitizen`, `pep621`, `poetry`, `cargo`, `npm`, `composer`, `uv`, and `scm`.
+- `cz changelog` generates Markdown changelogs.
+- `cz commit` supports `--dry-run` and `--write-message-to-file`.
+- `cz check` can validate a literal message, a commit-msg file, or a git revision range.
+
+## Suggested references
+
+- Command docs:
+  - `docs/commands/commit.md`
+  - `docs/commands/bump.md`
+  - `docs/commands/changelog.md`
+  - `docs/commands/check.md`
+  - `docs/commands/init.md`
+- Config docs:
+  - `docs/config/configuration_file.md`
+  - `docs/config/option.md`
+  - `docs/config/bump.md`
+- Automation docs:
+  - `docs/tutorials/github_actions.md`
+  - `docs/tutorials/gitlab_ci.md`
+- Error handling:
+  - `docs/exit_codes.md`
+
+## Examples
+
+- Validate one message: `cz check --message "feat(cli): add release command"`
+- Validate branch history: `cz check --rev-range master..HEAD`
+- Preview the next version: `cz bump --get-next`
+- Preview bump details: `cz bump --dry-run`
+- Preview changelog output: `cz changelog --dry-run`
+- Initialize configuration: `cz init`

.github/CODEOWNERS

@@ -10,20 +10,59 @@ jobs:
     if: ${{ github.repository == 'commitizen-tools/commitizen' && !startsWith(github.event.head_commit.message, 'bump:') }}
     runs-on: ubuntu-latest
     name: "Bump version and create changelog with commitizen"
+    permissions:
+      contents: write
+      actions: write
     steps:
+      - uses: actions/create-github-app-token@v3
+        id: app-token
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.PRIVATE_KEY }}
       - name: Check out
         uses: actions/checkout@v6
         with:
+          token: ${{ steps.app-token.outputs.token }}
           fetch-depth: 0
-          token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
-      - name: Create bump and changelog
-        uses: commitizen-tools/commitizen-action@master
+          fetch-tags: true
+      - name: Get GitHub App User ID
+        id: get-user-id
+        run: echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+      - uses: commitizen-tools/setup-cz@main
         with:
-          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-          changelog_increment_filename: body.md
+          # Information extracted from the app token
+          # Under actions/create-github-app-token is documented how to generate username and email for the bot
+          git-user-name: "${{ steps.app-token.outputs.app-slug }}[bot]"
+          git-user-email: "${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com"
+      - id: bump-version
+        run: |
+          old_sha="$(git rev-parse HEAD)"
+          cz --no-raise 21 bump --yes
+
+          if [ "$(git rev-parse HEAD)" = "$old_sha" ]; then
+            echo "No bump-eligible commits found, skipping release."
+            echo "bumped=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          echo "bumped=true" >> $GITHUB_OUTPUT
+          git push --follow-tags
+          new_version="$(cz version -p)"
+          echo "new_version=$new_version" >> $GITHUB_OUTPUT
+          new_version_tag="$(cz version -p --tag)"
+          echo "new_version_tag=$new_version_tag" >> $GITHUB_OUTPUT
+      - name: Build changelog for Release
+        if: steps.bump-version.outputs.bumped == 'true'
+        env:
+          NEW_VERSION: ${{ steps.bump-version.outputs.new_version }}
+        run: |
+          cz changelog --dry-run "${NEW_VERSION}" > .changelog.md
       - name: Release
-        uses: ncipollo/release-action@v1
-        with:
-          tag: v${{ env.REVISION }}
-          bodyFile: "body.md"
-          skipIfReleaseExists: true
+        if: steps.bump-version.outputs.bumped == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NEW_VERSION_TAG: ${{ steps.bump-version.outputs.new_version_tag }}
+        run: |
+          gh release create "${NEW_VERSION_TAG}" --notes-file .changelog.md

.github/workflows/bumpversion.yml

@@ -41,6 +41,7 @@ jobs:
 
           if [[ -n "$(git status --porcelain)" ]]; then
             git commit -m "docs(cli/screenshots): update CLI screenshots" -m "[skip ci]"
+            git pull --rebase origin master
             git push
           else
             echo "No changes to commit. Skipping."

.github/workflows/docspublish.yml

@@ -12,7 +12,7 @@ jobs:
       issues: write
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/github-script@v8
+      - uses: actions/github-script@v9
         with:
           script: |
             const issue = await github.rest.issues.get({

.github/workflows/label_issues.yml

@@ -18,7 +18,7 @@ jobs:
       with:
         configuration-path: .github/labeler.yml
     - name: Label based on PR title
-      uses: actions/github-script@v8
+      uses: actions/github-script@v9
       with:
         script: |
           const title = context.payload.pull_request.title.toLowerCase();

.github/workflows/label_pr.yml

@@ -24,7 +24,7 @@ jobs:
 
       - name: Broken Links Report
         if: steps.lychee.outputs.exit_code != 0 && github.event_name == 'schedule'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const fs = require('fs');

.github/workflows/links.yml

@@ -58,12 +58,12 @@ jobs:
           uv run --no-sync poe ci
         shell: bash
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         if: ${{ needs.detect_changes.outputs.relevant == 'true' }}
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Upload test results to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         if: ${{ needs.detect_changes.outputs.relevant == 'true' && !cancelled() }}
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/pythonpackage.yml

@@ -1,5 +1,6 @@
 name: Upload Python Package
 
+# The tag is now triggered by the Github App: CommitizenBot
 on:
   push:
     tags:
@@ -15,8 +16,8 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
           fetch-depth: 0
+          ref: ${{ github.ref_name }}
       - name: Set up Python
         uses: astral-sh/setup-uv@v7
       - name: Build

.github/workflows/pythonpublish.yml

@@ -56,7 +56,7 @@ repos:
           - tomli
 
   - repo: https://github.com/commitizen-tools/commitizen
-    rev: v4.13.9 # automatically updated by Commitizen
+    rev: v4.16.0 # automatically updated by Commitizen
     hooks:
       - id: commitizen
       - id: commitizen-branch