fix(changelog): allow --no-incremental to override changelog_incremental config

[bearomorphism]

Description

The "Bump version" workflow run failed while building GitHub release notes:

--incremental cannot be combined with a rev_range
Process completed with exit code 20.

Root cause

This is not a general --dry-run failure. It requires the interaction of two repository-specific behaviors:

1. ci: restore changelog updates #2074 enabled both update_changelog_on_bump = true and changelog_incremental = true. Incremental generation is intentional for cz bump: it updates only the new section while preserving manually edited changelog history.

2. After the bump, .github/workflows/bumpversion.yml separately generates notes for the new GitHub Release with:

   cz changelog --dry-run "${NEW_VERSION}"

   The positional ${NEW_VERSION} is parsed as rev_range. The changelog command also inherited changelog_incremental = true from this repository's configuration, and Commitizen explicitly rejects combining incremental generation with a revision range.

The setup-cz example uses the same --dry-run <version> pattern, but it remains valid unless the consuming project also enables changelog_incremental. --dry-run itself only prints instead of writing the changelog; it neither enables incremental mode nor creates the conflict.

The CLI could enable incremental mode explicitly, but it could not disable a config-enabled value. --incremental used store_true with a False default, while the command resolved it as:

arguments.get("incremental") or config.settings.get("changelog_incremental")

Therefore an omitted flag and an explicit false value were indistinguishable, and a configured True always won.

Fix

• Use argparse.BooleanOptionalAction for --incremental, adding the paired --no-incremental option and using None when neither form is supplied.
• Give an explicit CLI value precedence over changelog_incremental; fall back to configuration only when neither CLI form is supplied.
• Run the release-note command with --no-incremental, because it requests one exact release by revision while cz bump should continue using incremental generation.
• Add a regression test for --no-incremental with changelog_incremental = true and a revision range.
• Update command documentation, help snapshots for Python 3.10-3.14, and the generated help SVG.

This preserves the behavior introduced by #2074 for the repository changelog while allowing the separate release-note step to select its required non-incremental mode.

Alternatives considered

• Removing changelog_incremental = true would make the release-note command work again, but would undo ci: restore changelog updates #2074's protection of manually edited changelog history during cz bump.
• Removing the positional version would no longer request the exact release section needed by gh release create.

Checklist

• I have read the contributing guidelines

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

• Yes (GitHub Copilot)

Generated-by: GitHub Copilot following the guidelines

Code Changes

• Added a regression test for the exact failed precedence path.
• Regenerated versioned CLI help fixtures and the changelog help SVG.
• Ran targeted changelog, common-command, and CLI tests: 136 passed.
• Verified Ruff formatting/linting and mypy for the changed Python files.
• Rebased onto current master.

Steps to Test

1. With changelog_incremental = true, run cz changelog --dry-run 4.18.1; it retains the existing conflict because no override was requested.
2. Run cz changelog --no-incremental --dry-run 4.18.1; it generates that release without reading incremental mode from configuration.
3. Run uv run pytest -q tests/commands/test_changelog_command.py tests/commands/test_common_command.py tests/test_cli.py.

[github-actions]

🔍 Commitizen bump preview

Merging this PR will produce the following bump:

bump: version 4.18.1 → 4.18.2
tag to create: v4.18.2
increment detected: PATCH

## v4.18.2 (2026-09-14)

### Fix

- **changelog**: allow --no-incremental to override changelog_incremental config

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.26%. Comparing base (4967717) to head (3b41e05).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2086   +/-   ##
=======================================
  Coverage   98.26%   98.26%           
=======================================
  Files          61       61           
  Lines        2829     2830    +1     
=======================================
+ Hits         2780     2781    +1     
  Misses         49       49           

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

[bearomorphism]

Pushed the .github/workflows/bumpversion.yml update (now using workflow-scoped credentials): the release-notes step now runs cz changelog --no-incremental --dry-run "${NEW_VERSION}". This PR now contains the full fix for the pipeline failure.

[bearomorphism]

Interesting... I didn't know --no-XXX works

[Copilot]

🟡 Changes recommended

Add the requested regression test and refresh the stale changelog help artifact.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds --no-incremental support so CLI arguments override changelog_incremental configuration, fixing release-note generation.

Changes:

• Updates changelog flag precedence and release workflow usage.
• Documents the override and refreshes Python-version help fixtures.

File summaries

File	Summary
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_14_changelog_.txt	Updated changelog help fixture.
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_13_changelog_.txt	Updated changelog help fixture.
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_12_changelog_.txt	Updated changelog help fixture.
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_11_changelog_.txt	Updated changelog help fixture.
tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_10_changelog_.txt	Updated changelog help fixture.
docs/commands/changelog.md	Documents the incremental override.
commitizen/commands/changelog.py	Applies CLI-over-config precedence. Moderate (3 votes): add a regression test for --no-incremental with configured incremental mode and a revision range. Nit (1 vote): clarify the comment to mention the required flag.
commitizen/cli.py	Adds the boolean optional incremental flag. Nit (1 vote): regenerate the checked-in changelog help SVG.
.github/workflows/bumpversion.yml	Uses --no-incremental when generating release notes.

Review details

Suppressed comments (2)

commitizen/cli.py:417

• This changes the rendered changelog help, but the checked-in docs/images/cli_help/cz_changelog___help.svg still shows only --incremental and the old description. Because docs/commands/changelog.md embeds that artifact and the regeneration workflow runs only on master, the documentation shipped with this change is stale; regenerate and include the SVG update.

                        "action": argparse.BooleanOptionalAction,
                        "default": None,

commitizen/commands/changelog.py:85

• This comment describes a bare cz changelog <rev_range> as opting out, but with no CLI flag incremental_arg is None and the following expression still falls back to the configured value. Under changelog_incremental = true, that bare invocation still raises; mention the required --no-incremental flag in the example.

        # argument is `None` and we fall back to the config value. This lets a
        # one-off invocation (e.g. `cz changelog <rev_range>`) opt out of an
        # incremental default enabled in the configuration.

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[woile]

I don't understand, why do we need the --no-incremental? what changed?
All of the examples are just with --dry-run, it would mean that all the workflows are broken, or what am i missing?

https://github.com/commitizen-tools/setup-cz/blob/main/examples/bump-release.yaml#L44-L49

Can you rebase? I think there are already a bunch of things in master

[bearomorphism]

hmm I have to go through the RCA again

[bearomorphism]

@woile Rebased onto current master (including #2087 and the latest screenshot update) and rewrote the RCA. The missing distinction was that --dry-run is not what broke: the failure only occurs when the project also has changelog_incremental = true and passes the positional version as rev_range. The setup-cz example remains valid for projects without that setting. Here, #2074 intentionally enabled incremental mode for the cz bump changelog update, but the subsequent exact-version release-note command inherited it unintentionally. --no-incremental lets that second command opt out without undoing #2074.

[bearomorphism]

I think there should be a better solution. Sorry I should config my agent's instruction to prevent it from making noisy comments.

[bearomorphism]

new PR is #2088

closing this one