Scope (required)

Scope MUST be a real module name from this project. See references/modules.md for the full list.

If unsure of the scope, check the file paths being changed — the top-level directory is usually the correct scope.

Subject (required)

Imperative mood: "add feature" not "added feature"
No period at the end
Max 72 characters total (including type and scope prefix)
Lowercase first letter

Body (optional)

Explain WHY, not WHAT (the diff shows what changed)
Wrap at 72 characters
Separate from subject with blank line

Breaking Changes

If the commit introduces a breaking change, add footer:

BREAKING CHANGE: <description of what breaks and migration path>

Examples

Good:

feat(auth): add JWT token refresh endpoint

Tokens now auto-refresh 5 minutes before expiry.
Previously users had to re-login after token expiration.

fix(parser): handle empty input without crashing

refactor(db): extract connection pooling to separate module

BREAKING CHANGE: DatabaseClient constructor no longer accepts
pool config. Use PoolConfig.create() instead.

Bad:

updated some stuff          ← no type, no scope, vague
feat: Add new Feature.      ← capitalized, period, missing scope
fix(misc): various fixes    ← "misc" is not a real module

git-commit-helper

Git Commit Message Guide

Format

Type (required)