fix(version_schemes): support arbitrary semver pre-release labels by bearomorphism · Pull Request #1548 · commitizen-tools/commitizen · GitHub

Description

Fixes #950

This PR fixes a bug where commitizen 3.x raises InvalidVersion (or InvalidVersionPart) when encountering git tags with arbitrary semver pre-release identifiers (e.g., v0.7.1-release, v0.0.1-SNAPSHOT). These are valid semver identifiers per SemVer §9, but the previous regex pattern didn't accept them.

Changes

1. Extended _VERSION_PATTERN regex (version_schemes.py)

The original regex only allowed alpha|beta|preview|rc|a|b|c as pre-release labels. The new pattern adds an additional branch [a-zA-Z-]+ that matches any alphabetical or hyphenated identifier, conforming to semver spec.

Before: (alpha|beta|preview|rc|a|b|c) — only PEP 440 labels accepted
After: (alpha|beta|preview|rc|a|b|c|[a-zA-Z-]+) — also accepts arbitrary labels

2. Widened prerelease parameter type from Prerelease | None to str | None

The Prerelease type alias is Literal["alpha", "beta", "rc"], which is too narrow when the system needs to handle arbitrary labels parsed from existing tags. The CLI still restricts user input to the three known labels; this type widening only affects the internal API.

3. Fixed generate_prerelease() comparison logic

The old code used startswith() to match the incoming prerelease label against the current pre-release phase. This was subtly buggy: "alphabeta".startswith("a") is True, so a label like "alphabeta" would incorrectly be treated as continuing an "alpha" series.

The new logic:

Normalizes the incoming label using the same mapping packaging uses internally ("alpha"→"a", "beta"→"b", "rc"→"rc", others→lowercase)
For known PEP 440 labels (a, b, rc): uses max() ordering to prevent down-bumping phases (e.g., won't go from b1 back to a2)
For arbitrary labels: uses strict equality comparison — no ordering assumptions since arbitrary labels have no defined precedence

This also fixes a potential case-sensitivity issue: "SNAPSHOT" in a tag is normalized to "snapshot" by packaging, so the comparison now lowercases the incoming label for arbitrary labels.

Root Cause Analysis

When commitizen discovers existing tags (e.g., during cz bump), it calls:

Version(tag_string)  →  packaging.version.Version.__init__()
                     →  self._regex.fullmatch(version)

The _regex on BaseVersion was inherited from packaging.version.Version, which only accepts PEP 440 pre-release labels. A tag like v0.7.1-release would fail the regex match and raise InvalidVersion.

By overriding _regex with a pattern that also accepts arbitrary identifiers, the version can be parsed successfully. The rest of the version logic (epoch, release, post, dev, local) remains unchanged.

Test Cases Added

Input Version	Increment	Prerelease	Expected Output
v1.0.0-reallyweird	PATCH	reallyweird	1.0.0-reallyweird1
v0.7.1-release	PATCH	release	0.7.1-release1
v0.0.1-SNAPSHOT	PATCH	SNAPSHOT	0.0.1-snapshot1

AI Disclosure

This PR was revived and updated with AI assistance (GitHub Copilot). The original fix concept came from the community contributor.

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

I will update this PR this week when I have bandwidth

Maybe we can adjust the workflow. Several PRs got closed just because the target branch is deleted

Yep, this was a temporary workflow. we usually don't receive this many PR and don't review this fast. Maybe worth rethink it to make a rc to avoid what we encountered yesterday as well

Updated PR with new description

Pull request overview

Extends Commitizen’s version parsing to avoid InvalidVersion failures when encountering git tags that use non-PEP440, SemVer-style prerelease labels (e.g., v0.7.1-release, v0.0.1-SNAPSHOT), addressing issue #950.

Changes:

Widen VersionProtocol.bump() / BaseVersion.bump() prerelease typing from a restricted Literal[...] to str | None.
Override packaging.version.Version’s parsing regex via BaseVersion._regex to accept additional prerelease labels.
Add SemVer/SemVer2 test cases to validate bumping with non-standard prerelease labels.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
commitizen/version_schemes.py	Broadens prerelease typing and overrides the underlying version regex used for parsing.
tests/utils.py	Updates test argument typing to match widened prerelease type (`str
tests/test_version_scheme_semver.py	Adds regression tests for SemVer bumping with arbitrary prerelease labels and v-prefixed tags.
tests/test_version_scheme_semver2.py	Adds a SemVer2 regression test for bumping with an arbitrary prerelease label.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Addressed. Added equivalent SemVer2 test cases for �0.7.1-release and �0.0.1-SNAPSHOT alongside the existing 1.0.0-reallyweird case.

Good catch. Widened the pattern from [a-z]+? to [a-z]+(?:-[a-z]+)* which now accepts hyphenated labels like pre-release. For labels containing digits (e.g., foo1bar), the regex structure separates the numeric suffix via the pre_n group (foo + 1), which is consistent with how packaging handles it. Purely numeric identifiers like 1.0.0-1 are already handled by the post_n1 group (numeric-only post release). I've updated the PR description to clarify this scoping.

Fixed. The negative lookahead now uses (\+|$) instead of just $, so reserved labels like post and dev are correctly excluded even when followed by a +local segment. Added a test case 1.0.0-release+local123 to verify this.

Addressed. Moved the _regex override from BaseVersion to SemVer (which SemVer2 inherits). Pep440 now retains the strict PEP 440 regex from packaging.version.Version. Added an explicit test test_pep440_rejects_arbitrary_prerelease_labels() to lock this in.

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 commitizen-tools#950 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Please, also test that the monorepo support is not broken by this:
https://commitizen-tools.github.io/commitizen/tutorials/monorepo_guidance/

is this the one officially shared?
https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string

I didn't know that, thanks for sharing.
I will take a look later.

This reply was written with AI assistance (GitHub Copilot).

No — we can't use the official semver regex directly. Here's why:

The official regex captures prerelease as a single blob:

(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)

But packaging.version.Version.__init__() expects separate named groups:

# From packaging/version.py:
self._pre = _parse_letter_version(match.group("pre_l"), match.group("pre_n"))
self._post = _parse_letter_version(match.group("post_l"), match.group("post_n1") or match.group("post_n2"))
self._dev = _parse_letter_version(match.group("dev_l"), match.group("dev_n"))
self._local = _parse_local_version(match.group("local"))

Incompatibilities with the official regex:

Aspect	Official semver regex	What packaging needs
Prerelease	Single prerelease group	Separate pre_l (label) + pre_n (number)
Release segments	Exactly 3 (MAJOR.MINOR.PATCH)	2+ segments (e.g., 1.0, 1.0.0.0)
Epoch	Not supported	epoch group (e.g., 2!1.0.0)
Post-release	Not supported	post_l, post_n1, post_n2 groups
Dev release	Not supported	dev_l, dev_n groups

Verification:

>>> from commitizen.version_schemes import Pep440, SemVer
>>> from packaging.version import Version as _PackagingVersion
>>> Pep440._regex is _PackagingVersion._regex  # Pep440 unchanged
True
>>> SemVer._regex is _PackagingVersion._regex  # SemVer uses extended pattern
False
>>> '_regex' in Pep440.__dict__  # Pep440 doesn't override
False
>>> '_regex' in SemVer.__dict__  # Only SemVer overrides
True

Instead, we extended packaging's existing PEP 440 regex to also accept arbitrary alphabetical/hyphenated labels in the pre_l group, keeping compatibility with packaging's internals. I'll add the link to the official regex in the code comment for reference.

well but you can use the semver regex, and modify the prerelease to split into letter and number, right?
It already covers a lot of cases (which we should probably test against as well)
https://regex101.com/r/Ly7O1x/3/

Like for example, this is a valid prerelease alpha0.valid 😱

let me check later when I have bandwidth. sorry I haven't verified the AI generated comments. (testing AI agents' capability recently)

regex is difficult...

no need to rush, take your time 🧘🏻

This reply was written with AI assistance (GitHub Copilot).

Verified — monorepo support is not broken.

Tests executed locally (Windows):

Test suite	Result
tests/test_tags.py	✅ Passed
tests/test_version_schemes.py	✅ Passed
tests/test_version_scheme_semver.py	✅ Passed
tests/test_version_scheme_semver2.py	✅ Passed
tests/test_version_scheme_pep440.py	✅ Passed
tests/providers/test_scm_provider.py	✅ Passed
tests/test_project_info.py	✅ Passed
Subtotal	327 passed
tests/commands/test_bump_command.py	✅ Passed (4 GPG-signing tests skipped — pre-existing local env issue)
tests/commands/test_changelog_command.py	✅ Passed
Subtotal	228 passed, 4 deselected

Why monorepo is unaffected:

Scope of change — only commitizen/version_schemes.py and test files are modified:

$ git diff master --name-only
commitizen/version_schemes.py
tests/test_version_scheme_pep440.py
tests/test_version_scheme_semver.py
tests/test_version_scheme_semver2.py
tests/utils.py

_regex override is scoped to SemVer only — Pep440 (the default scheme) retains packaging's strict regex:

>>> '_regex' in BaseVersion.__dict__
False
>>> '_regex' in Pep440.__dict__
False
>>> '_regex' in SemVer.__dict__
True  # only SemVer overrides
>>> Pep440._regex is packaging.version.Version._regex
True  # Pep440 unchanged

No changes to monorepo-relevant code paths — tag discovery, tag_format, ignored_tag_formats, changelog filtering by scope, and per-component config resolution are all untouched.
Pep440 rejection test added — test_pep440_rejects_arbitrary_prerelease_labels() explicitly verifies that Pep440("1.0.0-release"), Pep440("1.0.0-SNAPSHOT"), and Pep440("1.0.0-pre-release") all raise InvalidVersion.

bearomorphism requested review from Lee-W, noirbizarre and woile as code owners June 12, 2025 19:14

bearomorphism marked this pull request as draft June 12, 2025 19:14

github-actions Bot added pr-status: wait-for-review type: bug labels Jun 12, 2025

bearomorphism force-pushed the bear-fix-semver-not-fully-covered branch from 0972ba2 to 877fcd6 Compare June 12, 2025 19:26

bearomorphism commented Jun 12, 2025

View reviewed changes

Comment thread tests/test_version_scheme_semver.py Outdated

bearomorphism force-pushed the bear-fix-semver-not-fully-covered branch from 877fcd6 to da46193 Compare June 13, 2025 13:09

bearomorphism changed the title WIP fix semver not fully covered fix semver not fully covered Aug 13, 2025

bearomorphism marked this pull request as ready for review August 13, 2025 01:30

Lee-W added this to the 4.9.0 milestone Aug 17, 2025

Lee-W reviewed Aug 24, 2025

View reviewed changes

Comment thread tests/test_version_scheme_semver.py Outdated

Comment thread commitizen/version_schemes.py Outdated

Lee-W added pr-status: wait-for-response and removed pr-status: wait-for-review labels Aug 24, 2025

Lee-W force-pushed the v4-9-0-test branch from 69db5b4 to b313847 Compare August 28, 2025 02:28

bearomorphism force-pushed the bear-fix-semver-not-fully-covered branch from da46193 to 3081fff Compare September 8, 2025 08:34

github-actions Bot added the pr-status: wait-for-review label Sep 8, 2025

Lee-W modified the milestones: 4.9.0, 4.9.1 Sep 9, 2025

Lee-W force-pushed the v4-9-0-test branch from c700d66 to 8b969db Compare September 9, 2025 05:56

Lee-W deleted the branch commitizen-tools:master September 9, 2025 06:09

Lee-W closed this Sep 9, 2025

Lee-W reopened this Sep 9, 2025

Lee-W changed the base branch from v4-9-0-test to master September 9, 2025 14:22

Lee-W removed this from the 4.9.1 milestone Sep 9, 2025

Lee-W added this to the 4.9.2 milestone Sep 9, 2025

bearomorphism force-pushed the bear-fix-semver-not-fully-covered branch 2 times, most recently from 8ee1dbe to bb48144 Compare September 13, 2025 09:45

bearomorphism commented Sep 23, 2025

View reviewed changes

Comment thread commitizen/version_schemes.py Outdated

bearomorphism marked this pull request as draft September 27, 2025 02:13

bearomorphism mentioned this pull request Sep 27, 2025

Improve readability in version scheme tests #1631

Closed

bearomorphism force-pushed the bear-fix-semver-not-fully-covered branch 2 times, most recently from 565f319 to 72fbe95 Compare May 3, 2026 06:48

bearomorphism changed the title fix semver not fully covered fix(version_schemes): support arbitrary semver pre-release labels May 3, 2026

bearomorphism force-pushed the bear-fix-semver-not-fully-covered branch 2 times, most recently from 9198eb4 to 9235842 Compare May 3, 2026 11:25

bearomorphism marked this pull request as ready for review May 3, 2026 11:26

bearomorphism requested a review from Copilot May 3, 2026 11:28

Copilot started reviewing on behalf of bearomorphism May 3, 2026 11:28 View session

bearomorphism force-pushed the bear-fix-semver-not-fully-covered branch from 9235842 to 9fff07f Compare May 3, 2026 11:33

Copilot AI reviewed May 3, 2026

View reviewed changes

bearomorphism force-pushed the bear-fix-semver-not-fully-covered branch from 9fff07f to 4a72d21 Compare May 3, 2026 11:38

bearomorphism force-pushed the bear-fix-semver-not-fully-covered branch from 4a72d21 to ac1bc5f Compare May 3, 2026 11:41

woile reviewed May 4, 2026

View reviewed changes

+                      # arbitrary semver pre-release labels (issue #950)
+                      (
+                          VersionSchemeTestArgs(
+                              current_version="1.0.0-reallyweird",
+                              increment="PATCH",

+                                  (post|rev|r|dev)
+                                  [-_\.]?
+                                  ([0-9]+)?
+                              $)
+                              [a-z]+?                                   # match any letters (semver support)

+                                  (post|rev|r|dev)
+                                  [-_\.]?
+                                  ([0-9]+)?
+                              $)

                   """
                   A base class implementing the `VersionProtocol` for PEP440-like versions.
                   """
+                  _regex: re.Pattern = re.compile(_VERSION_PATTERN, re.VERBOSE | re.IGNORECASE)

+              # We cannot fully rely on packaging.version for semver-compatible parsing.
+              # This pattern is NOT applied to Pep440 scheme, which retains strict PEP 440 parsing.
+              # See: https://github.com/pypa/packaging/blob/14b83e15dbb9caa87c63646ba7808b2b5e460ce6/src/packaging/version.py#L117
+              _SEMVER_VERSION_PATTERN = r"""^\s*

fix(version_schemes): support arbitrary semver pre-release labels by bearomorphism · Pull Request #1548 · commitizen-tools/commitizen · GitHub

Uh oh!

Uh oh!

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

Conversation

bearomorphism commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

1. Extended _VERSION_PATTERN regex (version_schemes.py)

2. Widened prerelease parameter type from Prerelease | None to str | None

3. Fixed generate_prerelease() comparison logic

Root Cause Analysis

Test Cases Added

AI Disclosure

Uh oh!

Uh oh!

codecov Bot commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ JUnit XML file not found

Uh oh!

Uh oh!

Uh oh!

bearomorphism commented Sep 8, 2025

Uh oh!

bearomorphism commented Sep 9, 2025

Uh oh!

Lee-W commented Sep 9, 2025

Uh oh!

Uh oh!

bearomorphism commented May 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

woile commented May 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

woile May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bearomorphism commented May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bearomorphism commented Jun 12, 2025 •
edited
Loading

codecov Bot commented Jun 13, 2025 •
edited
Loading

woile May 6, 2026 •
edited
Loading