Fix/docs by woile · Pull Request #1924 · commitizen-tools/commitizen

woile · 2026-04-05T09:46:58Z

Description

Closes Broken docs #1922
Improves readability of docs
Recommend semver2 during init (if not python)

Checklist

I have read the contributing guidelines

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

NO

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

For the init:

Create new folder with mkdir -p /tmp/app && cd /tmp/app
cz init
Observe

Additional Context

woile · 2026-04-05T09:48:01Z

docs/commands/bump.md

 cz bump --yes
 ```

+### `--version-scheme`


I moved it to the bottom, to have a cohesive view of the cli options.

Eventually, version-scheme should have it's own section, where the differences between pep440 and semver are explained.

codecov · 2026-04-05T09:48:07Z

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1924   +/-   ##
=======================================
  Coverage   97.99%   97.99%           
=======================================
  Files          60       60           
  Lines        2689     2691    +2     
=======================================
+ Hits         2635     2637    +2     
  Misses         54       54

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

Copilot

Pull request overview

This PR updates Commitizen’s documentation structure/readability (addressing broken docs discoverability) and adjusts default versioning guidance/behavior toward semver2 for non-Python projects, alongside CI workflow modernization for bump/release automation.

Changes:

Update docs navigation and config docs (including adding version_provider/version_scheme details and reorganizing sidebar entries).
Change the default version scheme selection for non-Python projects from semver to semver2 (plus related test updates).
Revise GitHub Actions workflows to bump/tag/release via cz + gh, and enable manual publish dispatch.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
tests/test_project_info.py	Updates expectations for default `version_scheme` to `semver2`.
tests/commands/test_bump_command.py	Formatting-only change to parametrized test ids lambda.
pyproject.toml	Updates metadata/deps and build settings; adjusts Commitizen tool config.
mkdocs.yml	Reorders configuration nav to improve discoverability.
docs/tutorials/github_actions.md	Adds a tip pointing to `setup-cz`.
docs/config/version_provider.md	Spacing/readability tweaks around configuration examples.
docs/config/option.md	Renames “Misc” to “General” and expands option descriptions.
docs/config/bump.md	Adds `version_provider`/`version_scheme` sections and details.
docs/commands/changelog.md	Improves option docs with config-file examples and wording.
docs/commands/bump.md	Relocates/rewrites `--version-scheme` docs and examples.
commitizen/project_info.py	Defaults non-Python projects to `semver2`.
commitizen/exceptions.py	Adds type annotations for exception attributes.
.github/workflows/pythonpublish.yml	Adds `workflow_dispatch` input and checks out specified ref.
.github/workflows/bumpversion.yml	Replaces action-based bump/release with explicit `cz` + `gh` steps.

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

Copilot · 2026-04-06T09:45:25Z

pyproject.toml

    { name = "Tim Hsiung", email = "[email protected]" },
 ]
-license = { file = "LICENSE" }
+license-files = ["LICENSE"]


license-files only controls which files get included in the sdist/wheel; it does not declare the project’s license in metadata. Since the previous license = { file = "LICENSE" } and the MIT classifier were removed, the package will no longer advertise a license on PyPI. Consider restoring the license field (or a license-expression) and optionally keep license-files for inclusion.

Suggested change

license-files = ["LICENSE"]

license-files = ["LICENSE"]

license = { file = "LICENSE" }

Copilot · 2026-04-06T09:45:25Z

.github/workflows/pythonpublish.yml

        with:
-          token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
          fetch-depth: 0
+          ref: ${{ inputs.version || github.ref_name }}


inputs.version is only available for workflow_dispatch runs; on tag push runs this context can be undefined and cause expression evaluation to fail. Use github.event.inputs.version (with a fallback to github.ref_name) or gate the expression by event type.

Suggested change

ref: ${{ inputs.version || github.ref_name }}

ref: ${{ github.event.inputs.version || github.ref_name }}

.github/workflows/bumpversion.yml

Copilot · 2026-04-06T09:45:26Z

.github/workflows/bumpversion.yml

+          NEW_VERSION: ${{ steps.bump-version.outputs.new_version }}
+        run: |
+          cz changelog --dry-run "${NEW_VERSION}" > .changelog.md


cz changelog --dry-run "${NEW_VERSION}" treats the positional argument as a revision range/version selector and will still render the “Unreleased” header unless --unreleased-version is provided. For GitHub Release notes you likely want --unreleased-version "${NEW_VERSION_TAG}" (tag-formatted) so the notes are labeled with the released version.

Suggested change

NEW_VERSION: ${{ steps.bump-version.outputs.new_version }}

run: |

cz changelog --dry-run "${NEW_VERSION}" > .changelog.md

NEW_VERSION_TAG: ${{ steps.bump-version.outputs.new_version_tag }}

run: |

cz changelog --dry-run --unreleased-version "${NEW_VERSION_TAG}" > .changelog.md

Copilot · 2026-04-06T09:45:26Z

docs/tutorials/github_actions.md

+> [!TIP]
+> Check the new [setup-cz](https://github.com/marketplace/actions/setup-commitizen-cli) action, simple and with [examples](https://github.com/commitizen-tools/setup-cz/tree/main/examples)


MkDocs Material doesn’t support GitHub-style callouts (> [!TIP]) with the current mkdocs.yml extensions; it will render as a plain blockquote. Use the supported admonition syntax (!!! tip) (or enable a callout extension) so the tip renders correctly in the docs site.

Suggested change

> [!TIP]

> Check the new [setup-cz](https://github.com/marketplace/actions/setup-commitizen-cli) action, simple and with [examples](https://github.com/commitizen-tools/setup-cz/tree/main/examples)

!!! tip

Check the new [setup-cz](https://github.com/marketplace/actions/setup-commitizen-cli) action, simple and with [examples](https://github.com/commitizen-tools/setup-cz/tree/main/examples)

Copilot · 2026-04-06T09:45:27Z

docs/config/option.md

+- Options
+    - `cz_conventional_commits`: uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
+    - `cz_jira`: jira [smart commits](https://support.atlassian.com/bitbucket-cloud/docs/use-smart-commits/)
+    - `cz_customize`: (**not recommend**) customize the convention directly in the `TOML` file under `[tool.commitizen.customize]`, read [Customize in configuration file](../customization/config_file.md) for more. There's a plan to provide a different functionality.

-Name of the committing rules to use.
+You can write your own convention, and release it on pypi, check [Customizing through a python class](../customization/python_class.md).


The name options list has markdown/grammar issues that harm rendering/readability: - Options should be a proper list label (e.g., - Options:) and (**not recommend**) should be (**not recommended**); also “pypi”/“python” should be capitalized (PyPI/Python).

Copilot · 2026-04-06T09:45:27Z

docs/config/bump.md

+For a detail explanation, check the [version provider](./version_provider.md) section.
+Which includes, how to create your own version provider.
+
+**Available options**
+
+- `commitizen`: default version provider and stores the version in the `.cz.toml` itself under the key `version`


The version_provider section has a few inaccuracies/typos:

“For a detail explanation” → “For a detailed explanation”.

The commitizen provider stores the version in the active Commitizen config (pyproject/.cz.*), not specifically in .cz.toml.

Suggested change

For a detail explanation, check the [version provider](./version_provider.md) section.

Which includes, how to create your own version provider.

**Available options**

- `commitizen`: default version provider and stores the version in the `.cz.toml` itself under the key `version`

For a detailed explanation, check the [version provider](./version_provider.md) section.

Which includes, how to create your own version provider.

**Available options**

- `commitizen`: default version provider and stores the version in the active Commitizen config (`pyproject.toml` or `.cz.*`) under the key `version`

Copilot · 2026-04-06T09:45:27Z

docs/commands/bump.md

+
+1. Command line:
+```sh
+cz bump --version-scheme semver


The --version-scheme examples are inconsistent with the new recommendation of semver2: the command-line example uses semver (v1) while the config example uses semver2. Consider updating the CLI example to cz bump --version-scheme semver2 to avoid confusion.

Suggested change

cz bump --version-scheme semver

cz bump --version-scheme semver2

Copilot · 2026-04-06T09:45:27Z

docs/commands/changelog.md

 cz changelog --incremental
 ```

+This flag can be set in the configuration file with the key `changelog_incremental` under `tool.commitizen`


Missing trailing punctuation on these “can be set/updated in the configuration file…” sentences makes the option docs read like incomplete statements. Consider ending them with a period for consistency with surrounding sections.

Suggested change

This flag can be set in the configuration file with the key `changelog_incremental` under `tool.commitizen`

This flag can be set in the configuration file with the key `changelog_incremental` under `tool.commitizen`.

Lee-W

a few question and comments. some suggestion from copilot seems to be correct

Lee-W · 2026-04-06T13:47:55Z

.github/workflows/bumpversion.yml

        uses: actions/checkout@v6
        with:
          fetch-depth: 0
-          token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"


Why don't we need it anymore?

Lee-W · 2026-04-06T13:48:57Z

.github/workflows/bumpversion.yml

+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh workflow run pythonpublish.yml \
+            -f "version=${{ steps.bump-version.outputs.new_version_tag }}"


Will it trigger the workflow twice? (trigger it once here and the v... tag triggers another)

Lee-W · 2026-04-06T13:49:26Z

commitizen/exceptions.py



 class CommitizenException(Exception):
+    exit_code: ExitCode


why do we add it here?

woile added 3 commits April 5, 2026 09:47

fix: change deprecated value and bump versions

dee1efe

docs: improve readability

36d25d6

fix(init): set semver2 as default if not python

d822e4e

woile requested review from Lee-W and noirbizarre as code owners April 5, 2026 09:46

github-actions bot added pr-status: wait-for-review type: bug type: documentation labels Apr 5, 2026

woile commented Apr 5, 2026

View reviewed changes

woile requested a review from bearomorphism April 5, 2026 09:49

ci: use setup-cz

f629d1e

bearomorphism requested a review from Copilot April 6, 2026 09:37

Copilot started reviewing on behalf of bearomorphism April 6, 2026 09:37 View session

Copilot AI reviewed Apr 6, 2026

View reviewed changes

Lee-W reviewed Apr 6, 2026

View reviewed changes

	license-files = ["LICENSE"]
	license-files = ["LICENSE"]
	license = { file = "LICENSE" }

	ref: ${{ inputs.version \|\| github.ref_name }}
	ref: ${{ github.event.inputs.version \|\| github.ref_name }}

		> [!TIP]
		> Check the new [setup-cz](https://github.com/marketplace/actions/setup-commitizen-cli) action, simple and with [examples](https://github.com/commitizen-tools/setup-cz/tree/main/examples)

	cz bump --version-scheme semver
	cz bump --version-scheme semver2

	This flag can be set in the configuration file with the key `changelog_incremental` under `tool.commitizen`
	This flag can be set in the configuration file with the key `changelog_incremental` under `tool.commitizen`.

Uh oh!

Conversation

woile commented Apr 5, 2026

Description

Checklist

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

Code Changes

Documentation Changes

Expected Behavior

Steps to Test This Pull Request

Additional Context

Uh oh!

woile Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

woile Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Lee-W left a comment

Choose a reason for hiding this comment

Uh oh!

Lee-W Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Lee-W Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Lee-W Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Apr 5, 2026 •

edited

Loading