commit-messages

name	commit-messages
description	Commit message conventions for this repo — load before writing any git commit or PR title. Commits drive the generated release notes.

Format

Use Conventional Commits, plain and minimal:

<type>: <short description>

• No scope. Write feat: ..., not feat(ci): .... We do not use the optional (scope) — it is stripped from the release notes anyway and only adds noise.
• Description in the imperative mood, lower-case start, no trailing period: fix: correct ldflags package path.
• Keep the subject line concise; add a body (after a blank line) only when the why isn't obvious.

Types and their effect on release notes

Release notes are generated from commit messages by git-cliff (see cliff.toml). Only two types appear in the notes:

Type	Shows in notes under	Use for
feat	Features	a new user-facing capability
fix	Bug Fixes	a user-facing bug fix

All other types are valid and encouraged for clean history, but are hidden from release notes: refactor, perf, docs, style, test, build, ci, chore. Pick the most accurate type — don't inflate something to feat/fix just to make it appear in the notes.

Breaking changes

Mark a breaking change with ! after the type (e.g. feat!: drop legacy config format) or a BREAKING CHANGE: footer. This also drives the automatic major version bump in the release workflow.

Examples

feat: drain run backlog back-to-back with a job capacity guard
fix: prefer API key auth when basic auth is also configured
refactor: extract image build into a reusable workflow   # hidden from notes
ci: pin release tooling to a verified checksum            # hidden from notes
feat!: require run-controller API key from environment    # major bump