Development & Code · master area

Conventional Commits

type(scope): description — STORY-ref. The commit message is an artefact: it feeds the changelog, the release brief, and the postmortem trail. Half of writing a commit is reading what already happened.

Owners: Developer Phase it lives in: How We Build (Volume IV) The corpus principle this enacts: Every artifact in the chain is a hedge against the departure of the person who created it.

Where it lives in the chain

• How We Build · Commit discipline and the chain of catches — the canon

How to do this

• Convention — type is one of feat | fix | chore | refactor | test | docs | perf | build. No wip — work-in-progress doesn't ship.
• Convention — scope is a domain word from the brief (grading, auth, billing), not a folder name.
• Convention — description is what the change does, not what the developer did. "fix(grading): clamp negative balances at zero" — not "updated the renderer."
• Convention — story reference at the end: [GR-204]. Travels into the changelog and the postmortem.

What good commits look like

feat(grading): submit shortcut returns to next exam (GR-204)
fix(grading): clamp negative balances at zero, surface in red (GR-211)
refactor(grading): extract scoring fn to grader/domain (GR-204)
chore(deps): bump react to 19.0.1

The changelog generates itself. The release brief reads as prose. The postmortem can git log --grep=billing and see every change that touched the area. A team that writes "fixed stuff" 200 times produces a release with no narrative — and a postmortem that requires re-reading every diff to understand what shipped.

Related crafts

• Trunk-Based Development — small commits, often
• Changelog Generation — the downstream artefact
• Code Review — the reviewer reads the commit messages first