Commit Standards

Conventional Commits

A specification for adding human and machine readable meaning to commit messages. Used in industry for automated versioning, changelog generation, and team clarity.

Why Conventional Commits?

🤖

Automation

Semantic versioning, changelogs, and CI/CD pipelines parse your commits automatically.

📖

Clarity

Team members instantly understand what changed and why without reading code.

🔍

Searchability

Filter history by type: bugfixes, features, breaking changes—it's all tagged.

📊

Metrics

Analyze team productivity: feature velocity, bug trends, code quality signals.

Basic Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

feat

A new feature

feat(auth): add two-factor authentication

fix

A bug fix

fix(api): handle null response in webhook

docs

Documentation only

docs: update README with new endpoints

style

Code style (not logic)

style: format code with prettier

refactor

Code restructure, no feature change

refactor(db): extract query builders to utils

perf

Performance improvement

perf(cache): implement redis memoization

test

Add or update tests

test(auth): add password reset flow tests

chore

Build, deps, tooling (no code change)

chore: upgrade typescript to 5.2

Real Examples

Simple Fix (One-Liner)

fix(ui): correct button alignment on mobile

Feature with Scope

feat(payment): add stripe integration for subscriptions

With Detailed Body

refactor(auth): migrate session store to Redis

Previously used in-memory session storage which caused issues
in multi-instance deployments. Now uses Redis for shared state.

Benefits:
- Horizontal scaling enabled
- Session persistence across restarts
- Reduced memory footprint per instance

Tests updated to use mock Redis.

Breaking Change

feat(api)!: change pagination to cursor-based

BREAKING CHANGE: The /items endpoint no longer accepts 
offset/limit params. Use cursor-based pagination instead.

Old: GET /items?offset=10&limit=20
New: GET /items?cursor=xyz&limit=20

Scopes (Optional)

Scopes help identify which part of the system changed. Common examples:

feat(auth): ...      # authentication module
fix(api): ...        # api endpoints
refactor(db): ...    # database layer
docs(deployment): .. # deployment docs
perf(ui): ...        # frontend performance

Best Practices

  • Use imperative mood: "add" not "added", "fix" not "fixed"
  • No period at end: "add feature" not "add feature."
  • Lowercase description: "add feature" not "Add feature"
  • Keep subject under 50 chars: Readable in git logs and GitHub
  • Wrap body at 72 chars: For terminal readability
  • Explain what and why, not how: Code shows how; message explains intent
  • One logical change per commit: Makes history bisectable and reviewable
  • Breaking changes go in footer: Tools can parse and alert on these

Quick Reference with Aliases

Combine conventional commits with git-devkit aliases for a smooth workflow:

git s                    # check status
git ap                   # stage intentional hunks
git ds                   # review staged changes
git cm "feat(api): add endpoint"
git lg                   # inspect local history
git ps                   # push to remote

Tools & Integration

commitizen

Interactive prompt to write compliant commits

npm install -g commitizen

husky + commitlint

Git hooks to validate commits before push

npm install husky commitlint

semantic-release

Auto-version and changelog from commits

npm install -D semantic-release

standard-version

Manual versioning with conventional commits

npm install -D standard-version

Start Writing Better Commits Today

Pair conventional commits with git-devkit aliases for a complete, professional workflow. Your future self (and your team) will thank you when debugging production issues.

View All AliasesSee Real-World Impact