Commit Conventions

Conventional Commits

Standard format for commit messages that enables automated changelogs, semantic versioning, and clear project history.

When to Use

• Writing any git commit message
• Reviewing commit history for consistency
• Setting up commit linting (commitlint, husky)
• Generating changelogs or release notes
• Any time git commit is about to be executed

Core Patterns

Commit Message Structure

Follow this exact format:

(): 

The first line (subject) must be under 72 characters. Use imperative mood ("add feature" not "added feature" or "adds feature").

# Simple commit
git commit -m "feat: add user registration endpoint"

# With scope
git commit -m "fix(auth): prevent token refresh race condition"

# With body and footer
git commit -m "feat(api): add pagination to list endpoints

Implement cursor-based pagination for all collection endpoints.
Default page size is 20, max is 100.

Closes #142"

Commit Types

| Type | When to Use | Triggers Version Bump | |------------|------------------------------------------|-----------------------| | feat | New feature or capability | MINOR (0.X.0) | | fix | Bug fix | PATCH (0.0.X) | | refactor | Code change that neither fixes nor adds | None | | docs | Documentation only | None | | test | Adding or fixing tests | None | | chore | Maintenance, deps, tooling | None | | perf | Performance improvement | None | | ci | CI/CD configuration changes | None | | style | Formatting, whitespace, semicolons | None | | build | Build system or external deps | None | | revert | Reverts a previous commit | Depends |

Breaking Changes

Mark breaking changes with ! after the type/scope, and include a BREAKING CHANGE: footer:

# Breaking change with bang notation
git commit -m "feat(api)!: change authentication from API keys to OAuth2

BREAKING CHANGE: All API consumers must migrate to OAuth2 tokens.
API key authentication is removed entirely."

# Breaking change in refactor
git commit -m "refactor!: rename User model fields

BREAKING CHANGE: firstName -> givenName, lastName -> familyName.
Run migration 2024_03_rename_user_fields."

Scopes

Scopes indicate the area of the codebase affected. Keep them consistent within a project:

# Good: consistent, short scopes
feat(auth): add SSO login
fix(auth): handle expired refresh tokens
feat(api): add rate limiting middleware
fix(ui): correct modal z-index on mobile
chore(deps): upgrade express to v5
test(api): add integration tests for /users

# Bad: inconsistent or verbose scopes
feat(authentication-module): add SSO          # too verbose
fix(src/components/Modal): fix z-index        # file path as scope
feat(USER_API): add endpoint                  # inconsistent casing

Anti-Patterns

What NOT to Do

• Vague messages: fix: stuff, chore: updates, feat: changes
• Past tense: feat: added login page (use feat: add login page)
• Uppercase first letter: feat: Add login (use feat: add login)
• Trailing period: fix: correct null check. (drop the period)
• Multiple concerns: One commit doing a feat + fix + refactor — split them
• Missing type: update dependencies (use chore: update dependencies)
• Type as description: refactor: refactor auth module (use refactor(auth): extract token validation)

# BAD
git commit -m "fixed bug"
git commit -m "WIP"
git commit -m "feat: Added new feature to handle the user login flow and also fixed a bug"

# GOOD
git commit -m "fix(auth): prevent null pointer on missing session cookie"
git commit -m "feat(auth): add login flow with email verification"

Quick Reference

feat:     New feature                    -> MINOR version bump
fix:      Bug fix                        -> PATCH version bump
refactor: Code restructuring             -> No version bump
docs:     Documentation                  -> No version bump
test:     Tests                          -> No version bump
chore:    Maintenance                    -> No version bump
perf:     Performance                    -> No version bump
ci:       CI/CD changes                  -> No version bump
style:    Formatting only                -> No version bump
build:    Build system                   -> No version bump
revert:   Revert previous commit         -> Depends

Format:   (): 
Breaking: Add ! after type/scope + BREAKING CHANGE footer
Subject:  Imperative, lowercase, no period, under 72 chars
Body:     Wrap at 72 chars, explain WHY not WHAT

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VersoXBT
• Source: VersoXBT/claude-initial-setup
• License: MIT
• Homepage: https://github.com/VersoXBT/claude-initial-setup#installation

Install and usage instructions live in the source repository linked above.