cliff.toml

# git-cliff configuration. Produces, per release:
#
#   ## VERSION - DATE
#
#   ### Group
#
#   - [shorthash] Subject
#
# Regenerate with `uv run tox run -e changelog -- -o CHANGELOG.md`.
#
# --prepend caveat: git-cliff only recognises the `# Changelog` header
# above when it is followed by a blank line. CHANGELOG.md is committed as
# a bare `# Changelog\n` (gen_changelog.py and the end-of-file-fixer hook
# both strip trailing blank lines), so
# `--prepend` against it does not match the header and duplicates
# `# Changelog` at the bottom of the file instead of leaving it alone. Use
# `-o` for a full regeneration, not `--prepend`, against the committed
# file. `--prepend` also requires a commit range (or `-u`/`-l`), so the
# first release must use `-o` regardless.

[changelog]
header = "# Changelog\n\n"
body = """
{% if version %}\
## {{ version | trim_start_matches(pat="v") }} - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}\
## Unreleased
{% endif %}\
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | striptags | trim | upper_first }}

{% for commit in commits %}\
- [{{ commit.id | truncate(length=7, end="") }}] {{ commit.message | upper_first }}
{% endfor %}\
{% endfor %}\n
"""
trim = true
footer = ""

[git]
# Commit subjects land verbatim in a markdown list item, so a stray double
# space inside one is a diff the mdformat hook would make during the release.
# Only horizontal whitespace is collapsed: `\s+` would fold the blank line
# between subject and body into a space and drag the whole body onto the
# subject line.
commit_preprocessors = [
    { pattern = "[ \\t]{2,}", replace = " " },
]
conventional_commits = true
filter_unconventional = false
split_commits = false
protect_breaking_commits = false
filter_commits = false
tag_pattern = "v[0-9]*"
topo_order = false
sort_commits = "oldest"
# Group names carry `<!-- N -->` prefixes purely to force ordering; the
# template strips them with `striptags`. Without them `group_by` sorts
# alphabetically.
commit_parsers = [
    { message = "^chore\\(release\\)", skip = true },
    { message = "^Merge ", skip = true },
    { message = "^feat", group = "<!-- 0 -->Features" },
    { message = "^fix", group = "<!-- 1 -->Bug Fixes" },
    { message = "^perf", group = "<!-- 2 -->Performance" },
    { message = "^refactor", group = "<!-- 3 -->Refactoring" },
    { message = "^docs", group = "<!-- 4 -->Documentation" },
    { message = "^test", group = "<!-- 5 -->Testing" },
    { message = "^(build|ci)", group = "<!-- 6 -->Build & CI" },
    { message = "^(chore|style|format)", group = "<!-- 7 -->Chores" },
    { message = ".*", group = "<!-- 8 -->Other" },
]