Merge branch 'master' into v4-11-0

bearomorphism · web-flow · commit 7a8ac42e51c9 · 2025-12-29T19:18:11.000+08:00
diff --git a/.github/workflows/links.yml b/.github/workflows/links.yml
@@ -0,0 +1,40 @@
+name: Links
+
+on:
+  repository_dispatch:
+  workflow_dispatch:
+  pull_request:
+  schedule:
+    - cron: "00 18 * * *"
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write # required for peter-evans/create-issue-from-file
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Link Checker
+        id: lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          fail: false
+
+      - name: Broken Links Report
+        if: steps.lychee.outputs.exit_code != 0 && github.event_name == 'schedule'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const fs = require('fs');
+
+            // Read the markdown file
+            // Ensure the path is correct relative to the workspace root
+            const reportBody = fs.readFileSync('./lychee/out.md', 'utf8');
+
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Broken Links Report',
+              body: reportBody
+            });
diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,5 @@
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/commitizen-tools/commitizen/pythonpackage.yml?label=python%20package&logo=github&logoColor=white&style=flat-square)](https://github.com/commitizen-tools/commitizen/actions)
+[![Check Links](https://github.com/commitizen-tools/commitizen/actions/workflows/links.yml/badge.svg)](https://github.com/commitizen-tools/commitizen/actions/workflows/links.yml)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square)](https://conventionalcommits.org)
 [![PyPI Package latest release](https://img.shields.io/pypi/v/commitizen.svg?style=flat-square)](https://pypi.org/project/commitizen/)
 [![PyPI Package download count (per month)](https://img.shields.io/pypi/dm/commitizen?style=flat-square)](https://pypi.org/project/commitizen/)
@@ -45,7 +46,7 @@ This standardization makes your commit history more readable and meaningful, whi
 - 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
+- [Customizable](https://commitizen-tools.github.io/commitizen/customization/config_file/) commit rules and templates
 - Multi-format version file support
 - Custom rules and plugins via pip
 
@@ -174,7 +175,7 @@ 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)
+- [Version provider](https://commitizen-tools.github.io/commitizen/config/version_provider/)
 
 For all available options, see the [bump command documentation](https://commitizen-tools.github.io/commitizen/commands/bump/).
 
@@ -249,7 +250,7 @@ Commitizen provides a comprehensive CLI with various commands. Here's the comple
 
 - [Conventional Commits Specification][conventional_commits]
 - [Exit Codes Reference](https://commitizen-tools.github.io/commitizen/exit_codes/)
-- [Configuration Guide](https://commitizen-tools.github.io/commitizen/config/)
+- [Configuration Guide](https://commitizen-tools.github.io/commitizen/config/configuration_file/)
 - [Command Documentation](https://commitizen-tools.github.io/commitizen/commands/init/)
 
 ### Getting Help
diff --git a/docs/config/bump.md b/docs/config/bump.md
@@ -185,24 +185,24 @@ version_files = [
 
     ```json title="setup.json"
     {
-    "name": "magictool",
-    "version": "1.2.3",
-    "dependencies": {
-        "lodash": "1.2.3"
-    }
+        "name": "magictool",
+        "version": "1.2.3",
+        "dependencies": {
+            "lodash": "1.2.3"
+        }
     }
     ```
 
     After running `cz bump 2.0.0`, its content will be updated to:
 
     ```diff title="setup.json"
     {
-    "name": "magictool",
-    - "version": "1.2.3",
-    + "version": "2.0.0",
-    "dependencies": {
-        "lodash": "1.2.3"
-    }
+        "name": "magictool",
+    -   "version": "1.2.3",
+    +   "version": "2.0.0",
+        "dependencies": {
+            "lodash": "1.2.3"
+        }
     }
     ```
 
diff --git a/docs/config/version_provider.md b/docs/config/version_provider.md
@@ -19,6 +19,7 @@ Commitizen includes several built-in version providers for common package manage
 The default version provider stores and retrieves the version from your Commitizen configuration file (e.g., `pyproject.toml`, `.cz.toml`, etc.).
 
 **Use when:**
+
 - You want to keep version management separate from your package manager
 - Your project doesn't use a standard package manager
 - You need maximum flexibility in version management
@@ -35,6 +36,7 @@ version = "0.1.0"  # Required when using this provider
 Fetches the version from Git tags using `git describe`. This provider **only reads** version information and never writes it back to files. It's designed to work with tools like `setuptools-scm` or other package manager `*-scm` plugins that derive version numbers from Git history.
 
 **Use when:**
+
 - You're using `setuptools-scm` or similar tools
 - You want version numbers derived from Git tags
 - You don't want Commitizen to modify any files for version management
@@ -54,6 +56,7 @@ version_provider = "scm"
 Manages version in `pyproject.toml` under the `project.version` field, following [PEP 621](https://peps.python.org/pep-0621/) standards.
 
 **Use when:**
+
 - You're using a modern Python project with PEP 621-compliant `pyproject.toml`
 - You want version management integrated with your Python project metadata
 
@@ -75,6 +78,7 @@ version = "0.1.0"  # Managed by Commitizen
 Manages version in `pyproject.toml` under the `tool.poetry.version` field, which is used by the [Poetry](https://python-poetry.org/) package manager. This approach is recommended only for users running Poetry versions earlier than 2.0 or relying on Poetry-specific features. For most users on Poetry 2.0 or later, it is recommended to use `pep621` instead. [Read More](https://python-poetry.org/docs/main/managing-dependencies/)
 
 **Use when:**
+
 - You're using Poetry < 2.0 as your Python package manager
 - You're using Poetry >= 2.0 as your Python package manager, but don't need poetry-specific features
 - You want Commitizen to manage the version that Poetry uses
@@ -101,6 +105,7 @@ Manages version in both `pyproject.toml` (`project.version`) and `uv.lock` (`pac
     Even though uv follows PEP 621 format, `pep621` does not manage the version in `uv.lock`. `uv` is still suggested for uv users.
 
 **Use when:**
+
 - You're using `uv` as your Python package manager
 - You want version synchronization between `pyproject.toml` and `uv.lock`
 
@@ -115,6 +120,7 @@ version_provider = "uv"
 Manages version in both `Cargo.toml` (`package.version`) and `Cargo.lock` (`package.version` for the matching package name). This ensures consistency between your Rust project's manifest and lock file.
 
 **Use when:**
+
 - You're working with a Rust project using Cargo
 - You want Commitizen to manage Rust package versions
 
@@ -136,6 +142,7 @@ version = "0.1.0"  # Managed by Commitizen
 Manages version in `package.json` and optionally synchronizes with `package-lock.json` and `npm-shrinkwrap.json` if they exist.
 
 **Use when:**
+
 - You're working with a Node.js/JavaScript project
 - You want Commitizen to manage npm package versions
 
@@ -158,6 +165,7 @@ version_provider = "npm"
 Manages version in `composer.json` under the `version` field, used by PHP's Composer package manager.
 
 **Use when:**
+
 - You're working with a PHP project using Composer
 - You want Commitizen to manage Composer package versions
 
diff --git a/docs/external_links.md b/docs/external_links.md
@@ -14,6 +14,6 @@
 - [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)
+- [Continuous delivery made easy (in Python)](https://blog.devgenius.io/continuous-delivery-made-easy-in-python-c085e9c82e69)
 
 [automatizando]: https://youtu.be/t3aE2M8UPBo
diff --git a/docs/faq.md b/docs/faq.md
@@ -120,7 +120,7 @@ If you would like to learn more about both schemes, there are plenty of good res
 - [API Versioning from Stripe](https://stripe.com/blog/api-versioning)
 - [Discussion about pip's use of CalVer](https://github.com/pypa/pip/issues/5645#issuecomment-407192448)
 - [Git Version Numbering](https://code.erpenbeck.io/git/2021/12/16/git-version-numbering/)
-- [SemVer vs. CalVer and Why I Use Both](https://mikestaszel.com/2021/04/03/semver-vs-calver-and-why-i-use-both/) (but not at the same time)
+- [SemVer vs. CalVer and Why I Use Both](https://mikestaszel.com/post/semver-vs-calver-and-why-i-use-both/) (but not at the same time)
 - [Semver Will Not Save You](https://hynek.me/articles/semver-will-not-save-you/)
 - [Why I Don't Like SemVer](https://snarky.ca/why-i-dont-like-semver/)
 
diff --git a/docs/tutorials/github_actions.md b/docs/tutorials/github_actions.md
@@ -113,13 +113,14 @@ jobs:
           poetry install
       - name: Build and publish
         env:
-          PYPI_USERNAME: __token__
-          PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
-        run: |
-          ./scripts/publish
+          POETRY_HTTP_BASIC_PYPI_USERNAME: __token__
+          POETRY_HTTP_BASIC_PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: poetry publish --build
 ```
 
-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 to publish the package.
+
+
 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/writing_commits.md b/docs/tutorials/writing_commits.md
@@ -46,6 +46,6 @@ Emojis may be added as well (e.g., see [cz-emoji][cz_emoji]), which requires the
 
 [customization]: ../customization/config_file.md
 [conventional_commits]: https://www.conventionalcommits.org
-[cz_emoji]: https://commitizen-tools.github.io/commitizen/third-party-commitizen/#cz-emoji
+[cz_emoji]: https://commitizen-tools.github.io/commitizen/third-party-plugins/cz-emoji/
 [configuration]: ../config/commit.md#encoding
 [breaking-change-config]: ../config/commit.md#breaking_change_exclamation_in_title
diff --git a/lychee.toml b/lychee.toml
@@ -0,0 +1,5 @@
+exclude_path = ["./tests"]
+
+exclude = [
+    "https://blog.devgenius.io/continuous-delivery-made-easy-in-python-c085e9c82e69" # Membership only article, sometimes it's 403 forbidden
+]
