feat(conventional_commits): allow exclamation in title on BC

Add a configuration (disable by default) to allow exclamation in
commit title to ease identify BC simple git log parsing.

Signed-off-by: Sebastien Fusilier <sebastien.fusilier@gmail.com>

Author: bastien31

commitizen/cz/conventional_commits/conventional_commits.py

@@ -154,17 +154,15 @@ def message(self, answers: ConventionalCommitsAnswers) -> str:  # type: ignore[o
         footer = answers["footer"]
         is_breaking_change = answers["is_breaking_change"]
 
-        if scope:
-            # example: "fix(users): email pattern corrected"
-            first_line = f"{prefix}({scope}): {subject}"
-        else:
-            # example: "fix: email pattern corrected"
-            first_line = f"{prefix}: {subject}"
-
+        scope = f"({scope})" if scope else ""
+        body = f"\n\n{body}" if body else ""
+        title = f"{prefix}{scope}"
         if is_breaking_change:
+            if self.config.settings.get("breaking_change_exclamation_in_title", False):
+                title = f"{title}!"
             footer = f"BREAKING CHANGE: {footer}"
 
-        return "\n\n".join(s for s in (first_line, body, footer) if s)
+        return f"{title}: {subject}{body}{footer}"
 
     def example(self) -> str:
         return (

commitizen/defaults.py

@@ -61,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] = [
@@ -109,6 +110,7 @@ class Settings(TypedDict, total=False):
     "always_signoff": False,
     "template": None,  # default provided by plugin
     "extras": {},
+    "breaking_change_exclamation_in_title": False,
 }
 
 MAJOR = "MAJOR"

docs/config.md

@@ -96,6 +96,15 @@ Use annotated tags instead of lightweight tags. [See difference][annotated-tags-
 
 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 also indicated by an exclamation mark in the commit title (e.g., `feat!: breaking change`).
+When false, breaking changes will be only indicated by `BREAKING CHANGE:` in the footer. [Read more][writing_commits]
+
 ### `retry_after_failure`
 
 - Type: `bool`
@@ -401,3 +410,4 @@ setup(
 [template-customization]: customization.md#customizing-the-changelog-template
 [annotated-tags-vs-lightweight]: https://stackoverflow.com/a/11514139/2047185
 [encoding]: tutorials/writing_commits.md#writing-commits
+[writing_commits]: tutorials/writing_commits.md#conventional-commits

docs/tutorials/writing_commits.md

@@ -13,6 +13,10 @@ add to your commit body the following `BREAKING CHANGE`.
 Using these three keywords will allow the proper identification of the semantic version.
 Of course, there are other keywords, but I'll leave it to the reader to explore them.
 
+Note: You can also indicate breaking changes by adding an exclamation mark in the commit title
+(e.g., `feat!: breaking change`) by setting the `breaking_change_exclamation_in_title`
+configuration option to `true`. [Read more][breaking-change-config]
+
 ## Writing commits
 
 Now to the important part: when writing commits, it's important to think about:
@@ -44,3 +48,4 @@ Emojis may be added as well (e.g., see [cz-emoji][cz_emoji]), which requires the
 [conventional_commits]: https://www.conventionalcommits.org
 [cz_emoji]: https://commitizen-tools.github.io/commitizen/third-party-commitizen/#cz-emoji
 [configuration]: ../config.md#encoding
+[breaking-change-config]: ../config.md#breaking_change_exclamation_in_title

tests/test_conf.py

@@ -105,6 +105,7 @@
     "always_signoff": False,
     "template": None,
     "extras": {},
+    "breaking_change_exclamation_in_title": False,
 }
 
 _new_settings: dict[str, Any] = {
@@ -143,6 +144,7 @@
     "always_signoff": False,
     "template": None,
     "extras": {},
+    "breaking_change_exclamation_in_title": False,
 }
 
 

tests/test_cz_conventional_commits.py

@@ -105,6 +105,55 @@ def test_breaking_change_in_footer(config):
     )
 
 
+@pytest.mark.parametrize(
+    "scope,breaking_change_exclamation_in_title,expected_message",
+    [
+        # Test with scope and breaking_change_exclamation_in_title enabled
+        (
+            "users",
+            True,
+            "feat(users)!: email pattern corrected\n\ncomplete content\n\nBREAKING CHANGE: migrate by renaming user to users",
+        ),
+        # Test without scope and breaking_change_exclamation_in_title enabled
+        (
+            "",
+            True,
+            "feat!: email pattern corrected\n\ncomplete content\n\nBREAKING CHANGE: migrate by renaming user to users",
+        ),
+        # Test with scope and breaking_change_exclamation_in_title disabled
+        (
+            "users",
+            False,
+            "feat(users): email pattern corrected\n\ncomplete content\n\nBREAKING CHANGE: migrate by renaming user to users",
+        ),
+        # Test without scope and breaking_change_exclamation_in_title disabled
+        (
+            "",
+            False,
+            "feat: email pattern corrected\n\ncomplete content\n\nBREAKING CHANGE: migrate by renaming user to users",
+        ),
+    ],
+)
+def test_breaking_change_message_formats(
+    config, scope, breaking_change_exclamation_in_title, expected_message
+):
+    # Set the breaking_change_exclamation_in_title setting
+    config.settings["breaking_change_exclamation_in_title"] = (
+        breaking_change_exclamation_in_title
+    )
+    conventional_commits = ConventionalCommitsCz(config)
+    answers = {
+        "prefix": "feat",
+        "scope": scope,
+        "subject": "email pattern corrected",
+        "is_breaking_change": True,
+        "body": "complete content",
+        "footer": "migrate by renaming user to users",
+    }
+    message = conventional_commits.message(answers)
+    assert message == expected_message
+
+
 def test_example(config):
     """just testing a string is returned. not the content"""
     conventional_commits = ConventionalCommitsCz(config)