commitizen-spdx-changelog 0.1.2

Commitizen changelog format plugin with YAML frontmatter awareness for REUSE/SPDX-compliant changelogs

𝗰𝗼𝗺𝗺𝗶𝘁𝗶𝘇𝗲𝗻-𝚜𝚙𝚍𝚡-𝓬𝓱𝓪𝓷𝓰𝓮𝓵𝓸𝓰

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.

Features

• SPDX-aware — strips ----delimited YAML frontmatter before parsing
• Correct version detection — no false positives from Apache-2.0 style headers
• Drop-in replacement — extends commitizen's built-in Markdown format
• Zero extra config — just set changelog_format = "spdx-markdown"

Why do I need this?

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.

[!NOTE] This plugin strips the front matter before parsing, so your changelog stays compliant, doc-generator-friendly, and commitizen-compatible — all at once.

Getting started

Installation

uv add commitizen-spdx-changelog
# or: pip install commitizen-spdx-changelog

[!TIP] See the docs landing page for a full overview, and the usage guide for furher setup and workflow instructions.

Configuration

In pyproject.toml:

[tool.commitizen]
changelog_format = "spdx-markdown"

Usage

cz bump --changelog

The plugin handles changelogs with SPDX frontmatter like:

---
# SPDX-FileCopyrightText: 2026 Pablo Hörtner <[e-mail]>
#
# SPDX-License-Identifier: Apache-2.0

icon: lucide/git-commit-vertical
---

# Changelog

## 0.4.0 (2026-06-08)
...

Development

direnv allow
uv sync --group dev

[!TIP] Running direnv allow will activate the devbox environment automatically. See the Devbox guide for all available commands and tools.

Contributing

[!NOTE] Bug reports, feature requests, and pull requests are welcome.

• See docs/contributing.md 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.

License

Distributed under the terms of the Apache License 2.0.

• Copyright © 2026 Pablo Hörtner