A commitizen changelog format plugin with YAML frontmatter awareness —
designed for REUSE/SPDX-compliant changelogs. No more false version detection
from license headers like Apache-2.0.
Warning: This project is in early development.
- SPDX-aware — strips
----delimited YAML frontmatter before parsing - Correct version detection — no false positives from
Apache-2.0style headers - Drop-in replacement — extends commitizen's built-in
Markdownformat - Zero extra config — just set
changelog_format = "spdx-markdown"
If you keep your changelog in docs/changelog.md instead of the project root,
placing it alongside your documentation lets readers of your published site who
might not directly browse the git repository stay informed about recent changes.
Documentation generators like Zensical, Docusaurus, and tools using Google's
Open Knowledge Format (OKF) require a YAML front matter for meta data.
When you apply a REUSE/SPDX license header with reuse annotate, the
header lands as a YAML comment inside the front matter, not as an HTML comment:
# SPDX-License-Identifier: Apache-2.0
The catch: commitizen's built-in Markdown format does not understand YAML
front matter. It reads Apache-2.0 as a version number, causing
cz bump --changelog to fail silently or produce wrong results.
This plugin strips the front matter before parsing, so your changelog stays compliant, doc-generator-friendly, and commitizen-compatible — all at once.
uv add commitizen-spdx-changelog
# or: pip install commitizen-spdx-changelogSee the docs landing page for a full overview, and the usage guide for further setup and workflow instructions.
In pyproject.toml:
[tool.commitizen]
changelog_format = "spdx-markdown"cz bump --changelogThe plugin handles changelogs with SPDX frontmatter like:
---
# SPDX-FileCopyrightText: 2026 Pablo Hörtner <redtux@pm.me>
#
# SPDX-License-Identifier: Apache-2.0
icon: lucide/git-commit-vertical
---
# Changelog
## 0.4.0 (2026-06-08)
...direnv allow
uv sync --group devRunning direnv allow will activate the devbox environment automatically. See
the Devbox guide for all available commands and tools.
Bug reports, feature requests, and pull requests are welcome.
See contributing for guidelines.
For documentation contributions, please follow these principles:
Write for humans, keep it minimal, update docs with code, delete dead content.
Every page in docs/ and the project README.md are held to these standards.
Copyright © 2026 Pablo Hörtner
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.