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

Type	Description	Semver	Example
feat	New feature	MINOR	feat: add user authentication
fix	Bug fix	PATCH	fix: resolve login redirect loop
docs	Documentation only	-	docs: update API reference
style	Formatting, whitespace	-	style: fix indentation in utils
refactor	Code change, no feature/fix	-	refactor: extract validation logic
perf	Performance improvement	PATCH	perf: optimize database queries
test	Adding/fixing tests	-	test: add unit tests for auth
build	Build system, dependencies	-	build: upgrade to Node 20
ci	CI/CD configuration	-	ci: add GitHub Actions workflow
chore	Maintenance tasks	-	chore: update .gitignore
revert	Revert previous commit	-	revert: undo feature flag change

Scopes

Scopes indicate the area of the codebase affected:

# Component/module scopes
feat(auth): add OAuth2 support
fix(api): handle timeout errors
docs(readme): add installation steps

# File-based scopes
style(eslint): update linting rules
build(docker): optimize image size

# Layer scopes
refactor(service): extract user service
test(e2e): add checkout flow tests

Breaking Changes

Mark breaking changes with ! or BREAKING CHANGE footer:

# Using ! notation
feat(api)!: change response format to JSON:API

# Using footer
feat(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 keys
instead 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 country
instead of shipping country for digital goods.

Fixes #456
Reviewed-by: Alice
Co-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 flow
fix: prevent duplicate form submissions
refactor: extract payment processing to service
perf: cache user preferences in memory
docs: add API authentication examples

Bad Examples

# Too vague
fix: fixed it
update: updates

# Wrong tense
feat: added new feature
fix: fixes the bug

# Too long
feat: 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't
see the change immediately.

The fix adds cache invalidation after successful profile updates
and ensures CDN purge for static assets.

Footer Tokens

Token	Purpose	Example
Fixes	Closes issue	Fixes #123
Closes	Closes issue	Closes #456
Refs	References issue	Refs #789
BREAKING CHANGE	Breaking change	BREAKING CHANGE: description
Reviewed-by	Reviewer credit	Reviewed-by: Name
Co-authored-by	Co-author credit	Co-authored-by: Name <email>

Integration with Tooling

Commitlint Configuration

// commitlint.config.js
module.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.yml
branches:
  - main
plugins:
  - "@semantic-release/commit-analyzer"
  - "@semantic-release/release-notes-generator"
  - "@semantic-release/changelog"
  - "@semantic-release/npm"
  - "@semantic-release/git"

Version Bumping Rules

Commit Type	Version Bump	Example
feat	Minor (0.X.0)	1.2.0 → 1.3.0
fix	Patch (0.0.X)	1.2.0 → 1.2.1
perf	Patch (0.0.X)	1.2.0 → 1.2.1
BREAKING CHANGE	Major (X.0.0)	1.2.0 → 2.0.0
Others	No bump	1.2.0 → 1.2.0

Commit Message Generator

When analyzing changes, generate a commit message:

# 1. Check staged changes
git 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 message
feat(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