feat(conventional_commits): Add exclamation on commit title for breaking change

.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

commitizen/cz/conventional_commits/conventional_commits.py

@@ -154,11 +154,21 @@ def message(self, answers: ConventionalCommitsAnswers) -> str:  # type: ignore[o
         footer = answers["footer"]
         is_breaking_change = answers["is_breaking_change"]
 
+        # Check if breaking change exclamation in title is enabled
+        breaking_change_exclamation_in_title = self.config.settings.get(
+            "breaking_change_exclamation_in_title", False
+        )
+
         if scope:
             scope = f"({scope})"
         if body:
             body = f"\n\n{body}"
         if is_breaking_change:
+            if breaking_change_exclamation_in_title:
+                if scope:
+                    scope = f"{scope}!"
+                else:
+                    prefix = f"{prefix}!"
             footer = f"BREAKING CHANGE: {footer}"
         if footer:
             footer = f"\n\n{footer}"

commitizen/defaults.py

@@ -8,9 +8,6 @@
 
 from commitizen.question import CzQuestion
 
-# Type
-Questions = Iterable[MutableMapping[str, Any]]  # TODO: deprecate this?
-
 
 class CzSettings(TypedDict, total=False):
     bump_pattern: str
@@ -64,6 +61,7 @@ class Settings(TypedDict, total=False):
     version_scheme: str | None
     version_type: str | None
     version: str | None
+    breaking_change_exclamation_in_title: bool
 
 
 CONFIG_FILES: list[str] = [
@@ -111,6 +109,7 @@ class Settings(TypedDict, total=False):
     "always_signoff": False,
     "template": None,  # default provided by plugin
     "extras": {},
+    "breaking_change_exclamation_in_title": False,
 }
 
 MAJOR = "MAJOR"
@@ -161,6 +160,10 @@ def get_tag_regexes(
     }
 
 
+# Type
+Questions = Iterable[MutableMapping[str, Any]]  # TODO: remove this in v5
+
+
 def __getattr__(name: str) -> Any:
     # PEP-562: deprecate module-level variable
 
@@ -176,6 +179,7 @@ def __getattr__(name: str) -> Any:
         "change_type_order": (CHANGE_TYPE_ORDER, "CHANGE_TYPE_ORDER"),
         "encoding": (ENCODING, "ENCODING"),
         "name": (DEFAULT_SETTINGS["name"], "DEFAULT_SETTINGS['name']"),
+        "Questions": (Questions, "Iterable[CzQuestion]"),
     }
     if name in deprecated_vars:
         value, replacement = deprecated_vars[name]

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

@@ -24,7 +24,7 @@ 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`
 
@@ -103,6 +103,15 @@ Default: `None`
 
 Create custom commit message, useful to skip CI. [Read more][bump_message]
 
+### `breaking_change_exclamation_in_title`
+
+Type: `bool`
+
+Default: `false`
+
+When true, breaking changes will be indicated by an exclamation mark in the commit title (e.g., `feat!: breaking change`).
+When false, breaking changes will be indicated by `BREAKING CHANGE:` in the footer. [Read more][breaking-change-exclamation]
+
 ### `retry_after_failure`
 
 Type: `bool`