Conventional Commits

Format all git commit messages according to the Conventional Commits 1.0.0 specification.

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Type Reference

Decision Framework

When determining commit type, ask:

• •Does it add new functionality? → feat
• •Does it fix broken functionality? → fix
• •Does it only affect documentation? → docs
• •Does it improve performance? → perf
• •Does it restructure code without changing behavior? → refactor
• •Does it only change code style/formatting? → style
• •Does it add/modify tests? → test
• •Does it change build system or dependencies? → build
• •Does it change CI/CD configuration? → ci
• •Is it maintenance or tooling? → chore

Message Best Practices

Description (first line)

• •Keep under 50 characters
• •Use imperative mood ("add" not "added")
• •Don't capitalize first letter
• •No period at end

Scope

• •Use clear, consistent names: feat(auth):, fix(api):, docs(readme):

Body

• •Include when change requires explanation
• •Explain why the change was made
• •Describe what problem it solves
• •Wrap at 72 characters per line

Footers

• •Fixes #123 - Reference issues
• •Co-authored-by: Name <email> - Credit contributors
• •BREAKING CHANGE: description - Breaking changes
• •Refs: #456, #789 - Related issues

Breaking Changes

Indicate breaking changes using either method:

feat!: remove deprecated API endpoint

feat(api)!: change authentication flow

fix: update validation logic

BREAKING CHANGE: validation now rejects empty strings

Command Execution

Critical: Use single quotes to avoid shell escaping issues with !:

# Correct - single quotes
git commit -m 'feat!: add new authentication flow'

# Incorrect - backslash escaping (DO NOT USE)
git commit -m "feat\!: add new authentication flow"

For multi-line messages, use HEREDOC:

git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 support

Implement OAuth2 authentication flow with support for
Google and GitHub providers.

BREAKING CHANGE: removes legacy session-based auth
EOF
)"

Workflow

1. •Check for staged changes: git diff --cached --stat
2. •If nothing staged: stage with git add first
3. •Review changes: git diff --cached
4. •Check recent style: git log --oneline -5
5. •Determine type using decision framework
6. •Write message following best practices
7. •Execute commit with single quotes
8. •Verify: git log -1

Quality Checks

Before committing, verify:

• • Message accurately describes the changes
• • Type correctly categorizes the change
• • Scope (if used) is meaningful and consistent
• • Breaking changes are properly marked with ! or footer
• • Description is clear and under 50 characters
• • Body wraps at 72 characters (if present)

Examples

Simple fix:

fix: prevent null pointer in user lookup

Feature with scope:

feat(api): add rate limiting to endpoints

With body:

refactor: extract validation into separate module

Move validation logic from controllers to dedicated
validator classes for better testability and reuse.

Breaking change:

feat!: upgrade to v2 API format

BREAKING CHANGE: response structure changed from
{data: [...]} to {items: [...], meta: {...}}

With issue reference:

fix(auth): resolve token refresh race condition

Fixes #234

Full Specification

For the complete Conventional Commits 1.0.0 specification including all rules and FAQ, see references/full-spec.md.