Skip to content

fix(conventional_commits): add missing version bump notes for all change types#1960

Open
bearomorphism wants to merge 1 commit intocommitizen-tools:masterfrom
bearomorphism:docs/issue-515-version-bump-notes
Open

fix(conventional_commits): add missing version bump notes for all change types#1960
bearomorphism wants to merge 1 commit intocommitizen-tools:masterfrom
bearomorphism:docs/issue-515-version-bump-notes

Conversation

@bearomorphism
Copy link
Copy Markdown
Collaborator

@bearomorphism bearomorphism commented May 9, 2026

Description

Closes #515

Adds explicit version-bump documentation for every Conventional Commit type, both in the interactive cz commit prompt and in the cz info output, so users can immediately see how each type affects semantic versioning under Commitizen's defaults. Also adds a "Recommended Reading on Versioning" docs section gathering the articles surfaced during the issue discussion.

The first task in the issue (fixing the inaccurate "fix + everything else" rule in the bump docs) was already addressed by #1452. This PR completes the remaining tasks:

  • Add notes in commit message instructions to identify what version bump occurs with all change types (e.g., Correlates with no version bump in SemVer)
  • Add the recommended-reading articles raised in the issue thread, per discussion with @Lee-W

What changed

  • commitizen/cz/conventional_commits/conventional_commits.py — every prompt choice now spells out its version-bump impact, using the Correlates with X in SemVer phrasing already established by fix and feat:

    • fix, feat (unchanged): already correlated with PATCH/MINOR
    • refactor, perf: "Correlates with PATCH in SemVer"
    • docs, style, test, build, ci: "Correlates with no version bump in SemVer"

    Reflects the actual default bump_map (per @woile's comment: "fix, refactor and perf are patch, not everything"), not the alternative spec-only mapping.

  • commitizen/cz/conventional_commits/conventional_commits_info.txt — clarifies that, on top of the Conventional Commits spec, Commitizen's defaults bump PATCH for refactor and perf, and don't bump for docs/style/test/build/ci. Notes that this can be customized via bump_map/bump_pattern.

  • docs/external_links.md — new "Recommended Reading on Versioning" section linking the articles cited by @adam-grant-hendry: Hynek's Semantic Versioning Will Not Save You, Brett Cannon's Why I don't like SemVer anymore, Donald Stufft's Versioning Software, Hyrum's Law, 0ver, CalVer, PEP 440, plus the Conventional Commits / SemVer specs.

  • docs/commands/bump.md — adds a clarifying sentence under the Version Increment Rules table for non-bumping types, plus a tip admonition cross-linking to the new reading list.

Checklist

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

  • Yes (please specify the tool below)

Generated-by: GitHub Copilot CLI following the guidelines

Code Changes

  • Run uv run poe all locally to ensure this change passes linter check and tests
    • poe lint (ruff + mypy): clean
    • Targeted tests around commit prompts/info (test_cz_conventional_commits.py, test_cz_search_filter.py, test_check_command.py, test_commit_command.py, test_cz_customize.py): 161 passed
    • Full test suite: 1274 passed; the 4 errors / 1 failure observed locally are pre-existing environmental issues (GPG keystore pollution and a Windows long-path flake), reproducible against master without these changes.
  • Update the documentation for the changes

Documentation Changes

  • Run uv run poe doc locally to ensure the documentation pages renders correctly (mkdocs build clean)
  • Check and fix any broken links (internal or external) — all 9 external links return HTTP 200; internal anchor external_links.md#recommended-reading-on-versioning verified in the rendered site.

Expected Behavior

Running cz commit shows the version-bump impact next to every change type, e.g.:

? Select the type of change you are committing
  > fix:      A bug fix. Correlates with PATCH in SemVer
    feat:     A new feature. Correlates with MINOR in SemVer
    docs:     Documentation only changes. Correlates with no version bump in SemVer
    style:    ... Correlates with no version bump in SemVer
    refactor: ... Correlates with PATCH in SemVer
    perf:     ... Correlates with PATCH in SemVer
    test:     ... Correlates with no version bump in SemVer
    build:    ... Correlates with no version bump in SemVer
    ci:       ... Correlates with no version bump in SemVer

cz info now also calls out Commitizen's defaults explicitly.

Steps to Test This Pull Request

  1. uv sync --frozen --group base --group test --group linters --group documentation
  2. uv run cz commit — observe the new version-bump notes in the change-type prompt.
  3. uv run cz info — observe the new paragraph clarifying Commitizen's defaults.
  4. uv run poe doc — visit external_links.md and commands/bump.md to verify the new section and cross-link render correctly.

Additional Context

@codecov
Copy link
Copy Markdown

codecov Bot commented May 9, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.23%. Comparing base (4b93a50) to head (1242932).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files
@@           Coverage Diff           @@
##           master    #1960   +/-   ##
=======================================
  Coverage   98.23%   98.23%           
=======================================
  Files          61       61           
  Lines        2779     2779           
=======================================
  Hits         2730     2730           
  Misses         49       49           

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

@bearomorphism bearomorphism force-pushed the docs/issue-515-version-bump-notes branch from 6e7b54a to eb1a4b8 Compare May 9, 2026 09:34
@bearomorphism bearomorphism changed the title docs(conventional_commits): clarify version bump per commit type fix(conventional_commits): add missing version bump notes for all change types May 9, 2026
…nge types

Closes commitizen-tools#515

* Update the cz commit prompt to state the version bump impact for every
  Conventional Commit type, matching the existing 'Correlates with X in
  SemVer' phrasing already used for fix and feat:
    - refactor, perf -> 'Correlates with PATCH in SemVer'
    - docs, style, test, build, ci -> 'Correlates with no version bump
      in SemVer'
* Update conventional_commits_info.txt to call out commitizen's defaults
  on top of the Conventional Commits specification.
* Add a 'Recommended Reading on Versioning' section in
  docs/external_links.md with the articles surfaced in the issue
  discussion (Hynek, Brett Cannon, Donald Stufft, Hyrum's Law, 0ver,
  CalVer, PEP 440) and cross-link it from docs/commands/bump.md.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@bearomorphism bearomorphism force-pushed the docs/issue-515-version-bump-notes branch from eb1a4b8 to 1242932 Compare May 9, 2026 09:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bumping rule is wrongly documented

1 participant