docs(config): split the configuration documentation into pages #1657

bearomorphism · 2025-11-19T09:13:45Z

Why

docs/config.md basically mixed the usage of options that is only used by different cz commands together. It would be better if those options are categorized.

Also, duplication of option usage documentation occurs. It should be fixed.

This PR categorized and centralizes those configuration file options, and remove the duplication of option usages.

The configuration file doc and version provider doc have their own pages now.

Checklist

Documentation Changes

Run poetry doc locally to ensure the documentation pages renders correctly
Check and fix any broken links (internal or external) in the documentation

docs/config/version_provider.md

docs/config/configuration_file.md

codecov · 2025-11-19T09:15:46Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.68%. Comparing base (120d514) to head (2fa81c7).
⚠️ Report is 852 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1657      +/-   ##
==========================================
+ Coverage   97.33%   98.68%   +1.34%     
==========================================
  Files          42       60      +18     
  Lines        2104     2656     +552     
==========================================
+ Hits         2048     2621     +573     
+ Misses         56       35      -21

Flag	Coverage Δ
unittests	`98.68% <ø> (+1.34%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

docs/config/settings.md

bearomorphism · 2025-11-19T13:51:25Z

I need time to review and improve it.

Lee-W · 2025-11-19T13:43:23Z

docs/config/configuration_file.md

+
+## Creating a Configuration File
+
+You can create a configuration file manually, or use Commitizen's interactive init command:


Suggested change

You can create a configuration file manually, or use Commitizen's interactive init command:

You can create a configuration file manually, or use Commitizen's interactive `init` command:

or

Suggested change

You can create a configuration file manually, or use Commitizen's interactive init command:

You can create a configuration file manually, or use Commitizen's interactive initialization command:

or just remove the init

or "It is recommended to create a configuration file via our cz init command." and add a link to init documentation

or "It is recommended to create a configuration file via our cz init command." and add a link to init documentation

This is also good

Creating a file manually sounds too advanced..

Or maybe we could add a link to the configuration page and not emphasize the manual creation part too much.

docs/config/option.md

Lee-W · 2025-11-19T13:48:25Z

docs/config/version_provider.md

+version = "0.1.0"  # Managed by Commitizen
+```
+
+### `poetry`


I think this only make sense for poetry < 2.0. for poetry >= 2.0, pep621 is suggested

Could you provide details or suggested changes? Thanks!

Yep, the following format is more for poetry < 2.0 or users that need specific poetry features. Most people using poetry >= 2.0 are suggested to use pep621

https://python-poetry.org/blog/announcing-poetry-2.0.0#supporting-the-project-section-in-pyprojecttoml-pep-621

Lee-W · 2025-11-19T13:49:08Z

docs/config/version_provider.md

+
+### `uv`
+
+Manages version in both `pyproject.toml` (`project.version`) and `uv.lock` (`package.version` for the matching package name). This ensures consistency between your project metadata and lock file.


It basically follows PEP621, would be better if we mention that

Could you provide suggested changes? Thanks

docs/config/version_provider.md

bearomorphism · 2025-11-19T16:21:20Z

Now it is ready for review. I will probably use AI to improve the wording in the documentation in some future PRs.

Let's improve the structure first.

Lee-W · 2025-11-30T04:40:48Z

docs/config/configuration_file.md

+1. `pyproject.toml` (in the `[tool.commitizen]` section)
+2. `.cz.toml`
+3. `.cz.json`
+4. `cz.json`
+5. `.cz.yaml`
+6. `cz.yaml`
+7. `cz.toml`


Interesting order... but I just verified it's correc

This can be another discussion ... the order doesn't make sense to me

I wonder should we throw a warning if there are multiple cz.* file. Not sure how other tools like eslint or prettier handles multiple configuration file edge case.

Yep, that would be a nice feature. 👍

docs/config/version_provider.md

Lee-W · 2025-11-30T04:46:31Z

docs/config/version_provider.md

+version = "0.1.0"  # Managed by Commitizen
+```
+
+### `poetry`


Yep, the following format is more for poetry < 2.0 or users that need specific poetry features. Most people using poetry >= 2.0 are suggested to use pep621

https://python-poetry.org/blog/announcing-poetry-2.0.0#supporting-the-project-section-in-pyprojecttoml-pep-621

docs/config/version_provider.md

Co-authored-by: Wei Lee <weilee.rx@gmail.com>

bearomorphism · 2025-11-30T08:29:41Z

docs/commands/bump.md

-
-See [Version Schemes](#version-schemes-version-scheme).
-
 ## Avoid raising errors


I think this can be in a separate page, like CI tutorial page

But probably in another PR if we want to do it

github-actions bot added pr-status: wait-for-review type: documentation labels Nov 19, 2025

bearomorphism commented Nov 19, 2025

View reviewed changes

docs/config/version_provider.md Show resolved Hide resolved

bearomorphism commented Nov 19, 2025

View reviewed changes

docs/config/configuration_file.md Show resolved Hide resolved

bearomorphism commented Nov 19, 2025

View reviewed changes

docs/config/settings.md Outdated Show resolved Hide resolved

bearomorphism marked this pull request as ready for review November 19, 2025 09:17

bearomorphism requested review from Lee-W, noirbizarre and woile as code owners November 19, 2025 09:17

bearomorphism force-pushed the doc-config-2 branch from d2a6dbe to 92fdf20 Compare November 19, 2025 09:18

bearomorphism marked this pull request as draft November 19, 2025 13:50

Lee-W reviewed Nov 19, 2025

View reviewed changes

bearomorphism mentioned this pull request Nov 19, 2025

Rename the option cz bump --files-only to --version-files-only #1658

Open

4 tasks

bearomorphism force-pushed the doc-config-2 branch from f1ac47b to 01c0409 Compare November 19, 2025 16:07

bearomorphism marked this pull request as ready for review November 19, 2025 16:18

bearomorphism force-pushed the doc-config-2 branch from 01c0409 to 449ac4d Compare November 21, 2025 06:31

This was referenced Nov 21, 2025

reorg customize.md #1663

Open

docs: make Customization a subtopic under Configuration (Fixes #1663) #1674

Open

Lee-W reviewed Nov 30, 2025

View reviewed changes

Lee-W added pr-status: wait-for-modification and removed pr-status: wait-for-review labels Nov 30, 2025

Lee-W added this to the Non core code changes milestone Nov 30, 2025

github-actions bot added the pr-status: wait-for-review label Nov 30, 2025

bearomorphism force-pushed the doc-config-2 branch from b5c3f96 to 54d9e58 Compare November 30, 2025 07:46

docs(config): split the configuration documentation into pages

2fa81c7

Co-authored-by: Wei Lee <weilee.rx@gmail.com>

bearomorphism force-pushed the doc-config-2 branch from 54d9e58 to 2fa81c7 Compare November 30, 2025 07:57

bearomorphism commented Nov 30, 2025

View reviewed changes


		## Creating a Configuration File

		You can create a configuration file manually, or use Commitizen's interactive init command:


		### `uv`

		Manages version in both `pyproject.toml` (`project.version`) and `uv.lock` (`package.version` for the matching package name). This ensures consistency between your project metadata and lock file.


		See [Version Schemes](#version-schemes-version-scheme).

		## Avoid raising errors

Uh oh!

docs(config): split the configuration documentation into pages #1657

Are you sure you want to change the base?

docs(config): split the configuration documentation into pages #1657

Conversation

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

Uh oh!

Why

Checklist

Documentation Changes

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

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

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bearomorphism commented Nov 19, 2025

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bearomorphism commented Nov 19, 2025 •

edited

Loading

codecov bot commented Nov 19, 2025 •

edited

Loading

bearomorphism commented Nov 19, 2025 •

edited

Loading