Git Commit Message Guide

Format

Every commit message MUST follow this structure:

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

[optional body]

[optional footer]

Type (required)

Type	When to use
feat	New feature or capability
fix	Bug fix
docs	Documentation only
refactor	Code change that neither fixes nor adds
test	Adding or updating tests
chore	Build, CI, tooling changes

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