ADR 0002 — Conventional commits for PR titles and commit messages¶
- Status: Accepted
- Date: 2026-05-24
- Deciders: @TheurgicDuke771
Context¶
With squash-merge as the only allowed merge method (ADR 0001), each PR becomes exactly one commit on main whose message is the PR title. The PR title format therefore drives the readability of git log and enables future automation (changelog generation, release notes).
Decision¶
Use Conventional Commits for all PR titles and individual commits.
Allowed type prefixes:
| Type | Use for |
|---|---|
feat: |
New user-facing functionality |
fix: |
Bug fix (PR body MUST include Fixes #N per working-agreement #3) |
chore: |
Tooling, dependencies, repo housekeeping |
docs: |
Documentation-only change (CLAUDE.md, ADRs, README, code comments) |
test: |
Test-only change |
refactor: |
Internal change with no behaviour change |
This is an intentional subset of the Conventional Commits spec. The spec also defines build:, ci:, perf:, style:, and revert:; we deliberately exclude them to keep the git log taxonomy small and unambiguous for a small team — build/CI changes ride chore:, performance work rides fix: or refactor:, formatting rides chore:/refactor:, and reverts use revert:-style PR titles only if the spec type is later adopted. Expand the table if a real need emerges.
Format: <type>(<optional-scope>): <imperative summary>
Examples:
- feat(orchestration): add Airflow callback webhook handler
- fix(adf): debounce duplicate trigger events within 30s window
- chore: pin GX Core to 1.4.2 (exact pin — ADR 0003 requires an exact version, not a range)
- docs: add ADR 0005 for severity tier weights
Consequences¶
Positive
- git log --oneline reads as a categorised changelog.
- Enables future tooling: auto-changelog, release-please, semantic versioning.
- PR titles are self-documenting.
Negative - One more thing for new contributors to learn. Mitigated: the PR template includes a "Type of change" checklist that nudges the right prefix.
Enforcement¶
- PR template includes the convention.
- Future enhancement (post-W1): a GitHub Action that fails CI if the PR title does not match the convention.