conventional-commits | developer

Stats

Actions

Tags

conventional-commits | developer

Conventional Commits

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

Core Workflow

Analyze changes: Review staged files and modifications
Determine type: Select appropriate commit type (feat, fix, etc.)
Identify scope: Optional component/module affected
Write description: Concise summary in imperative mood
Add body: Optional detailed explanation
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

One logical change per commit: Don't mix features with fixes
Commit early, commit often: Small, focused commits
Write for reviewers: Messages should explain why, not just what
Reference issues: Link to tickets/issues when applicable
Use scopes consistently: Establish team conventions
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