Feat/next version

[woile]

Description

Just display the next version based on commits:

# before this PR: 4.16.5
$ cz version -p --next
4.17.0
$ cz version -p --next --minor
17
$ cz version -p --next --major
4

This is useful, because it improves the scm provider workflow, which is read-only, based on the tag.
With this features users can easily write themselves:

next_version = $(cz version -p --next --tag)
git tag "$next_version"

TODO: Add tutorial for this

On top of that, it's useful for github/forgejo actions for example (not controlled by commitizen, so you'd still need to format the tag):

next_major = $(cz version -p --next --major)
git tag -f "v$next_major"

Checklist

• I have read the contributing guidelines

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

AI only assisted with testing

Code Changes

• Add test cases to all the changes you introduce
• Run uv run poe all locally to ensure this change passes linter check and tests
• Manually test the changes:
  • Verify the feature/bug fix works as expected in real-world scenarios
  • Test edge cases and error conditions
  • Ensure backward compatibility is maintained
  • Document any manual testing steps performed
• Update the documentation for the changes

Documentation Changes

• Run uv run poe doc locally to ensure the documentation pages renders correctly
• Check and fix any broken links (internal or external)

Expected Behavior

Steps to Test This Pull Request

# before this PR: 4.16.5
$ cz version -p --next
4.17.0
$ cz version -p --next --minor
17
$ cz version -p --next --major
4

Additional Context

[github-actions]

🔍 Commitizen bump preview

Merging this PR will produce the following bump:

bump: version 4.16.5 → 4.17.0
tag to create: v4.17.0
increment detected: MINOR

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.24%. Comparing base (f087597) to head (55b1b2c).
⚠️ Report is 3 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@ Coverage Diff @@## master #2036 +/- ##
=======================================
Coverage 98.23% 98.24% =======================================
Files 61 61 Lines 2784 2799 +15 =======================================
+ Hits 2735 2750 +15 
Misses 49 49 

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[woile]

@Lee-W@bearomorphism if you have some time 🙏🏻

[Copilot]

Pull request overview

This PR implements cz version --next support for deriving the next version from git commit history (mirroring cz bump’s increment detection), and updates tests/docs to reflect the new CLI behavior.

Changes:

• Implement --next USE_GIT_COMMITS in cz version by computing the increment from commits since the tag matching the current version.
• Add comprehensive test coverage for the new USE_GIT_COMMITS behavior (including major-version-zero and error cases).
• Update cz version --help snapshots and docs/commands/version.md to document the new usage and examples.

Reviewed changes

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

Show a summary per file

File	Description
commitizen/commands/version.py	Implements commit-derived next-version calculation for cz version --next USE_GIT_COMMITS.
commitizen/cli.py	Adjusts argument exclusivity so --next can be combined with --major/--minor/--tag etc.
commitizen/commands/changelog.py	Adjusts ChangelogArgs typing for file_name to allow None.
tests/commands/test_version_command.py	Adds tests validating git-commit-derived next version and associated errors.
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_10_version_.txt	Updates expected cz version --help output formatting.
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_11_version_.txt	Updates expected cz version --help output formatting.
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_12_version_.txt	Updates expected cz version --help output formatting.
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_13_version_.txt	Updates expected cz version --help output formatting.
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_14_version_.txt	Updates expected cz version --help output formatting.
docs/commands/version.md	Documents the new USE_GIT_COMMITS behavior and adds examples.
AGENTS.md	Updates agent guidance (testing AAA + documentation guidelines).

---

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

[bearomorphism]

LGTM