foundation
Good commit messages
Write messages that explain intent and impact, not only the files that changed.
A good commit message explains **why** and **what impact**, not only which files changed. Conventional structure:
fix(billing): reject duplicate invoice webhooks
Stripe may retry webhooks; idempotency key was ignored on
update path. Adds integration test and metrics counter.
Fixes #4821
| Part | Guidance | |------|----------| | Subject (~50 chars) | Imperative mood, scope optional | | Body | Motivation, trade-offs, migration notes | | Footer | Issue links, breaking-change markers |
Tools like Changesets and changelog generators consume message quality.
On interviews: imperative subject, body for non-obvious context, linking issues, conventional commits for automation.
Common pitfalls: subjects like "fix" or "update"; bodies that repeat the diff; templates that hide missing intent.
The trade-off is message discipline versus speed — invest more when the change is risky or cross-team.
Checklist:
- Write an imperative subject with clear scope.
- Explain why when context is not obvious.
- Link issues and note migrations or flags.
- Avoid empty templates.