Plan 01 — Problem and Goal

Context¶

Commitizen's built-in Markdown changelog format has no YAML frontmatter awareness. The RE_TITLE regex matches # lines inside frontmatter as headings, causing search_version to extract false versions (e.g. 2.0 from Apache-2.0). Upstream declined a hardcoded fix (woile's response) — the recommended path is a custom commitizen.changelog_format plugin.

See docs/changelog.md for the affected file and issue #2014 for the full discussion.

Tasks¶

Reproduce the bug. Run cz bump --dry-run --changelog against docs/changelog.md and confirm NoRevisionError (exit code 16) or false version detection.
- See scripts/reproduce_bug.py for reproduction.
Confirm upstream position. Issue #2014 is closed; woile's comment directs users to create a custom plugin — no fix expected upstream.
Document root cause. Added summary of why RE_TITLE matches # inside frontmatter and how search_version extracts 2.0 from Apache-2.0.
- See scripts/reproduce_bug.py docstring and Step 1 output.
Sign off on plugin approach. Confirmed — custom commitizen.changelog_format entry point is the agreed path forward.
Read upstream docs and templates. Reviewed the changelog template customization, config file customization, Python class customization, and cookiecutter template — summarized in reproduction script.
Read BaseFormat and Markdown sources. Reviewed (base-source, markdown-source) to understand the override points before Plan 02.

Dependencies¶

git repo with a commitizen-managed changelog containing SPDX frontmatter
commitizen>=3.0 installed locally (venv or uv tool)

Acceptance¶

Bug reproduced and confirmed
Upstream path is authoritatively closed
Plugin approach formally agreed by the team

Next¶

→ Continue to Plan 02 — Scaffolding