Git Commit Message Guide

Format

Every commit message MUST follow this structure:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Type (required)

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