Feat/next version

AGENTS.md

@@ -76,8 +76,40 @@ Always run at least `uv run ruff check --fix . && uv run ruff format .` before p
 - **Types**: Preserve or improve existing type hints.
 - **Errors**: Prefer `commitizen/exceptions.py` error types; keep messages clear for CLI users.
 - **Output**: Use `commitizen/out.py`; do not add noisy logging.
+- **Testing**: Follow the Arrange, Act, Assert (AAA) pattern. Visually separate these phases with blank lines or comments.
 
 ## When Unsure
 
 - Prefer **reading tests and documentation first** to understand the expected behavior.
 - When behavior is ambiguous, **assume backward compatibility** with current tests and docs is required.
+
+## Documentation Guidelines
+
+- 100% Coverage: Every new module, class, method, and function MUST have a docstring. No exceptions
+- Even simple functions or internal helpers require documentation to explain their context
+
+### Docstring Format: Modified Google Style
+
+Use Google Docstring Style with these major modifications:
+
+1. **NEVER include type hints in the docstring.** We rely exclusively on Python's PEP 484 type signatures.
+2. **Classes MUST include an example.** Any class documentation must contain a brief usage example formatted in Markdown.
+3. **Class Attributes MUST be documented.** The class docstring must document the instance variables initialized in `__init__` within an `Attributes:` section.
+
+**Format Rules:**
+
+- `Args:`, `Returns:`, and `Attributes:` sections must describe the _semantic meaning_ and _constraints_ of the variables, not their types.
+- Omit the type in the lists (e.g., use `user_id: The ID of the user`, NOT `user_id (int): The ID of the user`).
+
+### Content Focus: The "What" and "Why"
+
+Code explains _how_. Your docstrings must explain _what_ and _why_.
+
+When documenting, you may include:
+
+1. **The Core Intent** What business or technical rule is this solving?
+2. **Considerations:** Architectural choices. Why was this approach chosen over the obvious alternative? Why the complexity (if introduced)?
+3. **Discarded Approaches:** If a simpler method wasn't used (e.g., avoiding an ORM feature for raw SQL, or caching strategies), explain what was discarded and why.
+4. **Edge Cases & Gotchas:** What weird scenarios does this code handle?
+
+In the end, the reader must understand the intention behind the decisions, to avoid making the same mistakes.

commitizen/cli.py

@@ -583,7 +583,6 @@ def __call__(
  "const": "USE_GIT_COMMITS",
  "choices": ["USE_GIT_COMMITS"]
  + [str(increment) for increment in VersionIncrement],
- "exclusive_group": "group2",
  },
  {
  "name": "manual_version",

commitizen/commands/changelog.py

@@ -31,7 +31,7 @@ class ChangelogArgs(TypedDict, total=False):
  change_type_order: list[str]
  current_version: str
  dry_run: bool
- file_name: str
+ file_name: str | None
  incremental: bool
  merge_prerelease: bool
  rev_range: str

commitizen/commands/version.py

@@ -4,14 +4,20 @@
 
 from packaging.version import InvalidVersion
 
-from commitizen import out
+from commitizen import bump, factory, git, out
 from commitizen.__version__ import __version__
 from commitizen.config import BaseConfig
-from commitizen.exceptions import NoVersionSpecifiedError, VersionSchemeUnknown
+from commitizen.exceptions import (
+ NoCommitsFoundError,
+ NoPatternMapError,
+ NotAGitProjectError,
+ NoVersionSpecifiedError,
+ VersionSchemeUnknown,
+)
 from commitizen.providers import get_provider
 from commitizen.tags import TagRules
 from commitizen.version_increment import VersionIncrement
-from commitizen.version_schemes import Increment, get_version_scheme
+from commitizen.version_schemes import Increment, VersionProtocol, get_version_scheme
 
 
 class VersionArgs(TypedDict, total=False):
@@ -63,6 +69,9 @@ def __call__(self) -> None:
  or self.arguments.get("next")
  or self.arguments.get("manual_version")
  ):
+ # TODO: once `cz --version` is implemented, move `self.cz` back to __init__
+ self.cz = factory.committer_factory(self.config)
+
  version_str = self.arguments.get("manual_version")
  if version_str is None:
  try:
@@ -84,11 +93,15 @@ def __call__(self) -> None:
 
  if next_increment_str := self.arguments.get("next"):
  if next_increment_str == "USE_GIT_COMMITS":
+ # Only check under `git` to allow the user to do stuff like
+ # `cz version 1.2.3 --major`
+ if not git.is_git_project():
+ raise NotAGitProjectError()
+
  # TODO: implement USE_GIT_COMMITS by deriving the increment from
  # git history. This requires refactoring the bump logic out of
  # `commitizen/commands/bump.py` so it can be reused here. See #1678.
- out.error("--next USE_GIT_COMMITS is not implemented yet.")
- return
+ version = self._get_next_git_version(version)
 
  next_increment = VersionIncrement.from_value(next_increment_str)
  increment: Increment | None
@@ -100,6 +113,9 @@ def __call__(self) -> None:
  increment = "MINOR"
  else:
  increment = "MAJOR"
+
+ # TODO: Consider adding all the parameters `.bump` supports:
+ # prerelease, prerelease_offset,exact_increment, etc...
  version = version.bump(increment=increment)
 
  if self.arguments.get("major"):
@@ -139,3 +155,39 @@ def __call__(self) -> None:
 
  # If no arguments are provided, just show the installed commitizen version
  out.write(__version__)
+
+ def _get_next_git_version(
+ self, current_version: VersionProtocol
+ ) -> VersionProtocol:
+ """Calculate the next version based on commits."""
+ rules = TagRules.from_settings(self.config.settings)
+ current_tag = rules.find_tag_for(git.get_tags(), current_version)
+ commits = git.get_commits(current_tag.name if current_tag else None)
+
+ # No commits, there is no need to create an empty tag.
+ # Unless we previously had a prerelease.
+ if not commits and not current_version.is_prerelease:
+ raise NoCommitsFoundError("[NO_COMMITS_FOUND]\nNo new commits found.")
+
+ bump_map = (
+ self.cz.bump_map_major_version_zero
+ if self.config.settings["major_version_zero"]
+ else self.cz.bump_map
+ )
+ bump_pattern = self.cz.bump_pattern
+
+ if not bump_map or not bump_pattern:
+ raise NoPatternMapError(
+ f"'{self.config.settings['name']}' rule does not support bump"
+ )
+ increment = bump.find_increment(
+ commits, regex=bump_pattern, increments_map=bump_map
+ )
+
+ # TODO: Consider adding all the parameters `.bump` supports:
+ # prerelease, prerelease_offset,exact_increment, etc..
+ new_version = current_version.bump(
+ increment,
+ )
+
+ return new_version

docs/commands/version.md

@@ -13,15 +13,25 @@ Get the version of the installed Commitizen or the current project (default: ins
 
 - **`--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.
+- **`--next USE_GIT_COMMITS`**: derive the bump automatically from the commits since the tag matching the current version, using your commit rules' bump map (the same logic as `cz bump`). Passing `--next` with no value defaults to `USE_GIT_COMMITS`. If no tag matches the current version, all commits are considered. When there are no new commits (and the current version is not a pre-release), the command errors out. The functionality does not yet include advanced versioning like prereleases or exact_increment.
 - **`--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
+
+# Derive the next version from the commits since the current version's tag
+cz version --project --next USE_GIT_COMMITS
+# Equivalent shorthand (--next defaults to USE_GIT_COMMITS)
+cz version --project --next
+# Retrieve just the next major part of the version
+cz version --project --next --major
+# Works with a manual version too
+cz version 1.4.0 --next
+# Combine with --tag to format the derived version using your tag_format
+cz version --project --next --tag
 ```

tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_10_version_.txt

@@ -1,5 +1,6 @@
 usage: cz version [-h] [-r | -p | -c | -v]
- [--major | --minor | --tag | --patch | --next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
+ [--major | --minor | --tag | --patch]
+ [--next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
  [MANUAL_VERSION]
 
 Get the version of the installed commitizen or the current project (default:

tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_11_version_.txt

@@ -1,5 +1,6 @@
 usage: cz version [-h] [-r | -p | -c | -v]
- [--major | --minor | --tag | --patch | --next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
+ [--major | --minor | --tag | --patch]
+ [--next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
  [MANUAL_VERSION]
 
 Get the version of the installed commitizen or the current project (default:

tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_12_version_.txt

@@ -1,5 +1,6 @@
 usage: cz version [-h] [-r | -p | -c | -v]
- [--major | --minor | --tag | --patch | --next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
+ [--major | --minor | --tag | --patch]
+ [--next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
  [MANUAL_VERSION]
 
 Get the version of the installed commitizen or the current project (default:

tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_13_version_.txt

@@ -1,5 +1,5 @@
 usage: cz version [-h] [-r | -p | -c | -v] [--major | --minor | --tag |
- --patch | --next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
+ --patch] [--next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
  [MANUAL_VERSION]
 
 Get the version of the installed commitizen or the current project (default:

tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_14_version_.txt

@@ -1,5 +1,5 @@
 usage: cz version [-h] [-r | -p | -c | -v] [--major | --minor | --tag |
- --patch | --next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
+ --patch] [--next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
  [MANUAL_VERSION]
 
 Get the version of the installed commitizen or the current project (default: