cliff.toml

# git-cliff configuration -- generates CHANGELOG.md from conventional
# commits (QUI-480) per Keep-a-Changelog conventions.
#
# Run `make changelog` to regenerate CHANGELOG.md from `main`'s history.
# The release pipeline regenerates on each tagged release; see
# `.gitlab/ci/release.yml` and RELEASING.md for the full flow.
#
# v0.1.0 is tagged and a v0.2.0 cycle has started, so the whole file is
# now 100% generated from git history -- the static `footer` block that
# used to pin the v0.1.0 hand-written section here has been removed
# (see the note below `trim = true`).

[changelog]
# What lands at the top of CHANGELOG.md on every regeneration. Mirrors
# the preamble we hand-authored, so the file's framing stays stable.
header = """
# Changelog

All notable changes to the XQuad toolchain are recorded here. The
format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
versioning is [SemVer](https://semver.org/) across both the Rust
crates and the Python distributions (single version string across the
whole workspace).

"""

# Tera template rendering one release block (`## [version] - date`
# plus grouped `### <Section>` entries). Conventional-commit types are
# remapped to Keep-a-Changelog sections in `commit_parsers` below.
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 | upper_first }}
{% for commit in commits %}\
- {% if commit.scope %}**{{ commit.scope }}**: {% endif %}\
{{ commit.message | upper_first }}\
{% if commit.breaking %} \
**[BREAKING]**\
{% endif %}\
{% if commit.footers %}\
{% for footer in commit.footers %}\
{% if footer.token == "Fixes" or footer.token == "Implements" or footer.token == "Closes" %}\
 ({{ footer.token }} {{ footer.value }})\
{% endif %}\
{% endfor %}\
{% endif %}
{% endfor %}\
{% endfor %}\n
"""

trim = true

# The static `footer` block that used to live here (a hand-written
# `## [0.1.0] - YYYY-MM-DD` stub) is gone. It was pinned until a real
# v0.2.0 existed -- this file's header comment said to remove it once
# that happened, and it has. Left in place, git-cliff would emit the
# `[0.1.0]` heading twice on every regeneration: once from real history
# (v0.1.0 is tagged and generates its own section now) and once more
# from the stub, the second copy carrying the literal `YYYY-MM-DD`
# placeholder instead of the real release date.

[git]
# Only conventional commits feed the changelog. Anything pre-QUI-480
# that lacks a `<type>(<scope>):` prefix is silently dropped, so the
# pre-enforcement history doesn't pollute the output.
conventional_commits  = true
filter_unconventional = true

# Breaking changes survive even when their type would otherwise be
# filtered. Treat them as load-bearing regardless of category.
protect_breaking_commits = true

# Drop commits that don't match any commit_parsers below. Combined
# with `filter_unconventional` this keeps GitLab "Merge branch …"
# subjects -- which fail the conventional-commit grammar -- out of
# the output so they never produce a duplicate entry alongside the
# squashed change.
filter_commits = true
# Pre-v0.1.0 tags never had a real audience and are dropped outright.
skip_tags = "^v0\\.0\\."

# Which tags count as releases at all. Deliberately excludes rc tags
# (QUI-1096): an rc must never become a range boundary, or the rc's
# commits are orphaned out of the release that actually shipped them.
#
# This is `tag_pattern`, NOT a `-rc` clause bolted onto `skip_tags`,
# and the difference is load-bearing -- the two are not
# interchangeable. `skip_tags` suppresses a release from the OUTPUT but
# git-cliff still sees the tag and still treats it as a boundary. That
# is good enough when the upper bound of the range is itself a real tag
# (rendering `v0.2.1..v0.3.0` folds the skipped v0.3.0-rc1's commits
# into v0.3.0), but it silently fails on the pre-tag preview path,
# where the upper bound is a synthetic `--tag` override over untagged
# HEAD: there git-cliff drops the skipped release's commits instead of
# folding them, and `make changelog-release VERSION=v0.4.0` renders an
# EMPTY changelog -- zero sections, exit 0. That path is step 4 of
# RELEASING.md's pre-flight, so the failure mode is a release manager
# previewing notes, seeing nothing, and having no signal that anything
# is wrong.
#
# `tag_pattern` avoids the whole class of problem by making git-cliff
# not recognise rc tags as tags in the first place, so they are never
# boundaries on any path. Verified across all five non-rc tags with a
# predecessor plus the v0.4.0 preview: exactly one section each, with
# the rc's commits present inside the release that shipped them.
tag_pattern = "^v[0-9]+\\.[0-9]+\\.[0-9]+$"

topo_order   = false
sort_commits = "newest"

# Conventional-commit type -> Keep-a-Changelog section. `chore`,
# `style`, `test`, `ci`, `build` are deliberately dropped: they're
# bookkeeping and rarely user-visible. Anything truly user-facing
# under those types should be promoted to feat/fix/refactor instead.
#
# `release` is dropped for a narrower reason: it exists only as the
# subject of a release MR's squash commit, and that commit lands in
# the very range the notes for that version are rendered from. A
# "release: vX.Y.Z" entry on the vX.Y.Z page is a tautology.
#
# The merge-skip entry must stay first. Merge commits are dropped
# today only incidentally, because `filter_commits = true` drops
# whatever no parser matches -- but the catch-all `BREAKING CHANGE`
# parser below would pull a merge commit straight into the changelog
# if an MR description happened to contain that string. Matches both
# the historical "Merge branch ..." form and this repo's newer
# "merge: ..." form.
#
# `exclude_merge_commits = true` was tried instead and rejected: it is
# accepted by git-cliff 2.13.1 (the pinned version) and then silently
# ignored -- verified empirically by toggling the key with a parser in
# place that would match a merge commit and observing identical
# output either way. Do not reach for it again.
commit_parsers = [
    { message = "^[Mm]erge", skip = true },
    { message = "^feat", group = "Added" },
    { message = "^fix", group = "Fixed" },
    { message = "^perf", group = "Performance" },
    { message = "^refactor", group = "Changed" },
    # Reverts undo a prior change rather than removing a feature, so
    # they map to "Changed" -- "Removed" in Keep-a-Changelog is reserved
    # for deliberate feature removal (dropping an API, a CLI flag, …).
    { message = "^revert", group = "Changed" },
    { message = "^docs", group = "Documentation" },
    { message = "^security", group = "Security" },
    { message = "^deprecate", group = "Deprecated" },
    # Catch-all -- breaking changes from any other type still surface.
    { body = ".*BREAKING CHANGE.*", group = "Changed" },
    # Drop chore/style/test/ci/build/release silently.
    { message = "^chore", skip = true },
    { message = "^release", skip = true },
    { message = "^style", skip = true },
    { message = "^test", skip = true },
    { message = "^ci", skip = true },
    { message = "^build", skip = true },
]

# Auto-link any QUI-NNN reference appearing in a rendered entry to
# its Linear ticket. Catches both subject-line scope refs and the
# `Fixes QUI-NNN` / `Implements QUI-NNN` trailers rendered inline by
# the body template above.
[[git.link_parsers]]
pattern = "QUI-(\\d+)"
href    = "https://linear.app/quip-network/issue/QUI-$1"