fix(version_schemes): support arbitrary semver pre-release labels

Extend BaseVersion with a custom _VERSION_PATTERN regex that accepts
arbitrary pre-release identifiers (e.g., -release, -SNAPSHOT,
-reallyweird) instead of only PEP 440's alpha/beta/rc.

This fixes InvalidVersion errors when using tags like v0.7.1-release
or v0.0.1-SNAPSHOT with commitizen's changelog and bump commands.

Closes #950

Co-authored-by: Copilot <[email protected]>

Author: bearomorphism

commitizen/version_schemes.py

@@ -121,7 +121,10 @@ def __ne__(self, other: object) -> bool:
     def bump(
         self,
         increment: Increment | None,
-        prerelease: Prerelease | None = None,
+        # str instead of Prerelease to support arbitrary semver pre-release labels
+        # (e.g., "release", "SNAPSHOT") parsed from existing tags. The CLI still
+        # restricts user input to alpha/beta/rc via argparse choices.
+        prerelease: str | None = None,
         prerelease_offset: int = 0,
         devrelease: int | None = None,
         is_local_version: bool = False,
@@ -145,11 +148,57 @@ def bump(
 VersionScheme: TypeAlias = type[VersionProtocol]
 
 
+# Custom version pattern that extends packaging's PEP 440 regex to support
+# arbitrary semver pre-release labels (e.g., -release, -SNAPSHOT, -reallyweird).
+# Python's packaging library does not use semver; it predates it. We cannot fully
+# rely on packaging.version for semver-compatible parsing.
+# See: https://github.com/pypa/packaging/blob/14b83e15dbb9caa87c63646ba7808b2b5e460ce6/src/packaging/version.py#L117
+_VERSION_PATTERN = r"""^\s*
+    v?
+    (?:
+        (?:(?P<epoch>[0-9]+)!)?                           # epoch
+        (?P<release>[0-9]+(?:\.[0-9]+)*)                  # release segment
+        (?P<pre>                                          # pre-release
+            [-_\.]?
+            (?P<pre_l>
+                (?!                                       # negative lookahead to prevent
+                    [-_\.]?                               # matching post, rev, r, dev
+                    (post|rev|r|dev)
+                    [-_\.]?
+                    ([0-9]+)?
+                $)
+                [a-z]+?                                   # match any letters (semver support)
+            )
+            [-_\.]?
+            (?P<pre_n>[0-9]+)?
+        )?
+        (?P<post>                                         # post release
+            (?:-(?P<post_n1>[0-9]+))
+            |
+            (?:
+                [-_\.]?
+                (?P<post_l>post|rev|r)
+                [-_\.]?
+                (?P<post_n2>[0-9]+)?
+            )
+        )?
+        (?P<dev>                                          # dev release
+            [-_\.]?
+            (?P<dev_l>dev)
+            [-_\.]?
+            (?P<dev_n>[0-9]+)?
+        )?
+    )
+    (?:\+(?P<local>[a-z0-9]+(?:[-_\.][a-z0-9]+)*))?       # local version
+\s*$"""
+
+
 class BaseVersion(_BaseVersion):
     """
     A base class implementing the `VersionProtocol` for PEP440-like versions.
     """
 
+    _regex: re.Pattern = re.compile(_VERSION_PATTERN, re.VERBOSE | re.IGNORECASE)
     parser: ClassVar[re.Pattern] = _DEFAULT_VERSION_PARSER
     """Regex capturing this version scheme into a `version` group"""
 
@@ -184,8 +233,26 @@ def generate_prerelease(
         # https://packaging.python.org/en/latest/specifications/version-specifiers/#pre-releases
         # https://semver.org/#spec-item-11
         if self.is_prerelease and self.pre:
-            prerelease = max(prerelease, self.pre[0])
-            if prerelease.startswith(self.pre[0]):
+            current_pre_label = self.pre[0]
+            # packaging normalizes "alpha"→"a", "beta"→"b", "rc"→"rc"
+            _LABEL_TO_NORMALIZED = {"alpha": "a", "beta": "b", "rc": "rc"}
+            _KNOWN_PRE_LABELS = {"a", "b", "rc"}
+            normalized_prerelease = _LABEL_TO_NORMALIZED.get(
+                prerelease, prerelease.lower()
+            )
+
+            # The ordering logic (max) only makes sense for the known PEP 440
+            # labels where "a" < "b" < "rc" lexicographically. For arbitrary
+            # semver labels (e.g., "release", "SNAPSHOT"), we use strict equality
+            # since there's no defined ordering between them.
+            if (
+                current_pre_label in _KNOWN_PRE_LABELS
+                and normalized_prerelease in _KNOWN_PRE_LABELS
+            ):
+                prerelease = max(normalized_prerelease, current_pre_label)
+                if prerelease == current_pre_label:
+                    offset = self.pre[1] + 1
+            elif normalized_prerelease == current_pre_label:
                 offset = self.pre[1] + 1
 
         return f"{prerelease}{offset}"
@@ -232,7 +299,7 @@ def increment_base(self, increment: Increment | None = None) -> str:
     def bump(
         self,
         increment: Increment | None,
-        prerelease: Prerelease | None = None,
+        prerelease: str | None = None,  # str to support arbitrary semver labels
         prerelease_offset: int = 0,
         devrelease: int | None = None,
         is_local_version: bool = False,

tests/test_version_scheme_semver.py

@@ -250,6 +250,37 @@
             ),
             "1.0.0",
         ),
+        # arbitrary semver pre-release labels (issue #950)
+        (
+            VersionSchemeTestArgs(
+                current_version="1.0.0-reallyweird",
+                increment="PATCH",
+                prerelease="reallyweird",
+                prerelease_offset=0,
+                devrelease=None,
+            ),
+            "1.0.0-reallyweird1",
+        ),
+        (
+            VersionSchemeTestArgs(
+                current_version="v0.7.1-release",
+                increment="PATCH",
+                prerelease="release",
+                prerelease_offset=0,
+                devrelease=None,
+            ),
+            "0.7.1-release1",
+        ),
+        (
+            VersionSchemeTestArgs(
+                current_version="v0.0.1-SNAPSHOT",
+                increment="PATCH",
+                prerelease="SNAPSHOT",
+                prerelease_offset=0,
+                devrelease=None,
+            ),
+            "0.0.1-snapshot1",
+        ),
         # simple flow
         (
             VersionSchemeTestArgs(

tests/test_version_scheme_semver2.py

@@ -240,6 +240,17 @@
             ),
             "1.0.0",
         ),
+        # arbitrary semver pre-release labels (issue #950)
+        (
+            VersionSchemeTestArgs(
+                current_version="1.0.0-reallyweird",
+                increment="PATCH",
+                prerelease="reallyweird",
+                prerelease_offset=0,
+                devrelease=None,
+            ),
+            "1.0.0-reallyweird.1",
+        ),
         # simple_flow
         (
             VersionSchemeTestArgs(

tests/utils.py

@@ -18,13 +18,13 @@
     from freezegun.api import FrozenDateTimeFactory
     from pytest_mock import MockerFixture
 
-    from commitizen.version_schemes import Increment, Prerelease
+    from commitizen.version_schemes import Increment
 
 
 class VersionSchemeTestArgs(NamedTuple):
     current_version: str
     increment: Increment | None
-    prerelease: Prerelease | None
+    prerelease: str | None
     prerelease_offset: int
     devrelease: int | None