Conventional Commits

Conventional Commits

Write standardized, semantic commit messages that enable automated versioning and changelog generation.

Core Workflow

1. Analyze changes: Review staged files and modifications
2. Determine type: Select appropriate commit type (feat, fix, etc.)
3. Identify scope: Optional component/module affected
4. Write description: Concise summary in imperative mood
5. Add body: Optional detailed explanation
6. Include footer: Breaking changes, issue references

Commit Message Format

<type>[optional scope]: <description>
[optional body]
[optional footer(s)]

Commit Types

Scopes

Scopes indicate the area of the codebase affected:

# Component/module scopesfeat(auth): add OAuth2 supportfix(api): handle timeout errorsdocs(readme): add installation steps
# File-based scopesstyle(eslint): update linting rulesbuild(docker): optimize image size
# Layer scopesrefactor(service): extract user servicetest(e2e): add checkout flow tests

Breaking Changes

Mark breaking changes with ! or BREAKING CHANGE footer:

# Using ! notationfeat(api)!: change response format to JSON:API
# Using footerfeat(api): change response format
BREAKING CHANGE: Response now follows JSON:API specification.Clients must update their parsers.

Commit Message Examples

Simple Feature

feat: add dark mode toggle

Feature with Scope

feat(ui): add dark mode toggle to settings page

Bug Fix with Issue Reference

fix(auth): resolve session expiration race condition
The session refresh was racing with the expiration check,causing intermittent logouts.
Fixes #234

Breaking Change

feat(api)!: migrate to v2 response format
BREAKING CHANGE: All API responses now use camelCase keysinstead of snake_case. Update client parsers accordingly.
Migration guide: https://docs.example.com/v2-migration

Multiple Footers

fix(payments): correct tax calculation for EU customers
Updated tax calculation to use customer's billing countryinstead of shipping country for digital goods.
Fixes #456Reviewed-by: AliceCo-authored-by: Bob <[email protected]>

Revert Commit

revert: feat(auth): add OAuth2 support
This reverts commit abc123def456.
Reason: OAuth provider has rate limiting issues in production.Will re-implement with proper caching.

Description Guidelines

Do

• Use imperative mood: "add" not "added" or "adds"
• Keep under 72 characters
• Start with lowercase
• No period at the end
• Be specific and concise

Don't

• "Fixed bug" (too vague)
• "Updated stuff" (not descriptive)
• "WIP" (commit when ready)
• "misc changes" (split into separate commits)

Good Examples

feat: add email verification flowfix: prevent duplicate form submissionsrefactor: extract payment processing to serviceperf: cache user preferences in memorydocs: add API authentication examples

Bad Examples

# Too vaguefix: fixed itupdate: updates
# Wrong tensefeat: added new featurefix: fixes the bug
# Too longfeat: add a new feature that allows users to export their data in multiple formats including CSV, JSON, and XML

Body Guidelines

When to include a body:

• Changes need context or explanation
• Complex logic that isn't self-evident
• Breaking changes require migration info
• Multiple related changes in one commit

fix(cache): invalidate user cache on profile update
Previously, profile updates were not reflected until cache expiry.This caused confusion when users updated their avatar and didn'tsee the change immediately.
The fix adds cache invalidation after successful profile updatesand ensures CDN purge for static assets.

Footer Tokens

Integration with Tooling

Commitlint Configuration

// commitlint.config.jsmodule.exports = {  extends: ['@commitlint/config-conventional'],  rules: {    'type-enum': [      2,      'always',      [        'feat', 'fix', 'docs', 'style', 'refactor',        'perf', 'test', 'build', 'ci', 'chore', 'revert'      ]    ],    'scope-case': [2, 'always', 'kebab-case'],    'subject-case': [2, 'always', 'lower-case'],    'subject-max-length': [2, 'always', 72],    'body-max-line-length': [2, 'always', 100]  }};

Husky Pre-commit Hook

# .husky/commit-msg#!/bin/sh. "$(dirname "$0")/_/husky.sh"npx --no-install commitlint --edit "$1"

Package.json Setup

{  "devDependencies": {    "@commitlint/cli": "^18.0.0",    "@commitlint/config-conventional": "^18.0.0",    "husky": "^8.0.0"  },  "scripts": {    "prepare": "husky install"  }}

Semantic Release Integration

Conventional commits enable automated versioning:

# .releaserc.ymlbranches:  - mainplugins:  - "@semantic-release/commit-analyzer"  - "@semantic-release/release-notes-generator"  - "@semantic-release/changelog"  - "@semantic-release/npm"  - "@semantic-release/git"

Version Bumping Rules

Commit Message Generator

When analyzing changes, generate a commit message:

# 1. Check staged changesgit diff --cached --name-only
# 2. Analyze change type# - New files = likely feat# - Modified test files = test# - Modified docs = docs# - Bug-related keywords = fix
# 3. Identify scope from path# src/components/Button.tsx → components or ui# src/services/auth.ts → auth or services
# 4. Generate messagefeat(ui): add loading state to Button component

Best Practices

1. One logical change per commit: Don't mix features with fixes
2. Commit early, commit often: Small, focused commits
3. Write for reviewers: Messages should explain why, not just what
4. Reference issues: Link to tickets/issues when applicable
5. Use scopes consistently: Establish team conventions
6. Review before committing: git diff --cached to verify changes

Output Checklist

Every commit message should:

• Start with valid type (feat, fix, docs, etc.)
• Use imperative mood in description
• Keep description under 72 characters
• Include scope when applicable
• Mark breaking changes with ! or footer
• Reference related issues in footer
• Provide body for complex changes
• Follow team's scope conventions