fix(version): improve coverage, UX, and docs for cz version

- Rename VersionIncrement.safe_cast to from_value; add tests
- Map NONE to no bump; user-facing error for USE_GIT_COMMITS
- Add tests for patch component, unknown scheme, and default output
- Clarify get_version_scheme Protocol check; fix TagRules docstring example
- Document MANUAL_VERSION, --next, and --patch; refresh help fixtures/SVG

Made-with: Cursor

Author: bearomorphism

commitizen/cli.py

@@ -567,7 +567,10 @@ def __call__(
                     },
                     {
                         "name": ["--patch"],
-                        "help": "Output the patch version only. Need to be used with MANUAL_VERSION, --project or --verbose.",
+                        "help": (
+                            "Output the patch version only. Must be used with MANUAL_VERSION, "
+                            "--project, or --verbose."
+                        ),
                         "action": "store_true",
                         "exclusive_group": "group2",
                     },

commitizen/commands/version.py

@@ -11,7 +11,7 @@
 from commitizen.providers import get_provider
 from commitizen.tags import TagRules
 from commitizen.version_increment import VersionIncrement
-from commitizen.version_schemes import get_version_scheme
+from commitizen.version_schemes import Increment, get_version_scheme
 
 
 class VersionArgs(TypedDict, total=False):
@@ -84,12 +84,20 @@ def __call__(self) -> None:
 
             if next_increment_str := self.arguments.get("next"):
                 if next_increment_str == "USE_GIT_COMMITS":
-                    # TODO: implement this
-                    raise NotImplementedError("USE_GIT_COMMITS is not implemented")
+                    out.error("--next USE_GIT_COMMITS is not implemented yet.")
+                    return
 
-                next_increment = VersionIncrement.safe_cast(next_increment_str)
-                # TODO: modify the interface of bump to accept VersionIncrement
-                version = version.bump(increment=str(next_increment))  # type: ignore[arg-type]
+                next_increment = VersionIncrement.from_value(next_increment_str)
+                increment: Increment | None
+                if next_increment == VersionIncrement.NONE:
+                    increment = None
+                elif next_increment == VersionIncrement.PATCH:
+                    increment = "PATCH"
+                elif next_increment == VersionIncrement.MINOR:
+                    increment = "MINOR"
+                else:
+                    increment = "MAJOR"
+                version = version.bump(increment=increment)
 
             if self.arguments.get("major"):
                 out.write(version.major)

commitizen/tags.py

@@ -72,7 +72,7 @@ class TagRules:
     assert not rules.is_version_tag("warn1.0.0", warn=True)  # Does warn
 
     assert rules.search_version("# My v1.0.0 version").version == "1.0.0"
-    assert rules.extract_version("v1.0.0") == VersionProtocol("1.0.0")
+    assert rules.extract_version("v1.0.0") == rules.scheme("1.0.0")
     try:
         assert rules.extract_version("not-a-v1.0.0")
     except InvalidVersion:

commitizen/version_increment.py

@@ -1,13 +1,18 @@
+from __future__ import annotations
+
 from enum import IntEnum
 
 
 class VersionIncrement(IntEnum):
-    """An enumeration representing semantic versioning increments.
-    This class defines the four types of version increments according to semantic versioning:
-    - NONE: For commits that don't require a version bump (docs, style, etc.)
-    - PATCH: For backwards-compatible bug fixes
-    - MINOR: For backwards-compatible functionality additions
-    - MAJOR: For incompatible API changes
+    """Semantic versioning bump increments.
+
+    IntEnum keeps a total order compatible with NONE < PATCH < MINOR < MAJOR
+    for comparisons across the codebase.
+
+    - NONE: no bump (docs-only / style commits, etc.)
+    - PATCH: backwards-compatible bug fixes
+    - MINOR: backwards-compatible features
+    - MAJOR: incompatible API changes
     """
 
     NONE = 0
@@ -19,7 +24,7 @@ def __str__(self) -> str:
         return self.name
 
     @classmethod
-    def safe_cast(cls, value: object) -> "VersionIncrement":
+    def from_value(cls, value: object) -> VersionIncrement:
         if not isinstance(value, str):
             return VersionIncrement.NONE
         try:

commitizen/version_schemes.py

@@ -422,6 +422,10 @@ def get_version_scheme(
         raise VersionSchemeUnknown(f'Version scheme "{name}" unknown.')
     scheme = cast("type[VersionProtocol]", ep.load())
 
+    # `VersionProtocol` is a `@runtime_checkable` Protocol with properties, so
+    # `issubclass(scheme, VersionProtocol)` is not supported. The historical
+    # `isinstance(scheme, VersionProtocol)` check is only meaningful for instances;
+    # for loaded classes it is effectively a no-op for valid schemes.
     if not isinstance(scheme, VersionProtocol):
         warnings.warn(f"Version scheme {name} does not implement the VersionProtocol")
 

docs/commands/version.md

@@ -1,7 +1,27 @@
-Get the version of the installed Commitizen or the current project (default: installed commitizen)
+Get the version of the installed Commitizen or the current project (default: installed commitizen).
 
 ## Usage
 
 ![cz version --help](../images/cli_help/cz_version___help.svg)
 
-<!-- TODO: add documentation after this feature is stabilized -->
+## Project version and scheme
+
+- **`cz version --project`** prints the version from your configured [version provider](../config/version_provider.md).
+- **`cz version MANUAL_VERSION`** (optional positional) uses that string instead of the provider, so you can try how your configured scheme parses and formats it.
+
+## Components and next version
+
+- **`--major`**, **`--minor`**, **`--patch`**: print only that component of the (possibly manual) project version. Requires `--project`, `--verbose`, or a manual version.
+- **`--next` `[MAJOR|MINOR|PATCH|NONE]`**: print the version after applying that bump to the current project or manual version. `NONE` leaves the version unchanged.
+- **`--tag`**: print the version formatted with your `tag_format` (requires `--project` or `--verbose`).
+
+`--next USE_GIT_COMMITS` is reserved for a future feature (derive the bump from git history) and is not implemented yet.
+
+## Examples
+
+```bash
+cz version --project
+cz version 2.0.0 --next MAJOR
+cz version --project --major
+cz version --verbose
+```