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.