majiayu000 Conventional Commits Skill
This skill helps you create proper conventional commit messages for semantic versioning.
When to Use This Skill
- Creating git commits
- Ensuring semantic release works correctly
- Understanding commit message format
- Fixing commit message errors
- Planning version bumps
- Writing meaningful commit messages
Conventional Commits Format
<type>(<scope>): <subject>
<body>
<footer>
Required Elements
- type: Category of change (feat, fix, chore, etc.)
- subject: Brief description (imperative mood, lowercase, no period)
Optional Elements
- scope: Package or area affected (api, web, database, etc.)
- body: Detailed description
- footer: Breaking changes, issue references
Commit Types
Version Bumping Types
feat - New feature (minor version bump)
git commit -m "feat: add user authentication"
git commit -m "feat(api): add COE data endpoint"
fix - Bug fix (patch version bump)
git commit -m "fix: resolve database connection timeout"
git commit -m "fix(web): fix chart rendering issue"
feat! or BREAKING CHANGE - Breaking change (major version bump)
git commit -m "feat!: change API response format"
git commit -m "fix!: remove deprecated endpoints"
# Or with footer
git commit -m "feat: redesign auth system
BREAKING CHANGE: Auth tokens now use JWT format"
Non-Version Bumping Types
chore - Maintenance tasks, no production code change
git commit -m "chore: update dependencies"
git commit -m "chore(deps): upgrade Next.js to v16"
docs - Documentation only
git commit -m "docs: update README with deployment steps"
git commit -m "docs(api): add API documentation"
refactor - Code refactoring, no functional changes
git commit -m "refactor: simplify cache logic"
git commit -m "refactor(database): optimize query performance"
test - Adding or updating tests
git commit -m "test: add unit tests for auth service"
git commit -m "test(web): add E2E tests for checkout flow"
style - Code style changes (formatting, whitespace)
git commit -m "style: format code with Biome"
git commit -m "style: fix linting errors"
perf - Performance improvements
git commit -m "perf: optimize database queries"
git commit -m "perf(web): reduce bundle size"
ci - CI/CD changes
git commit -m "ci: add deployment workflow"
git commit -m "ci: fix GitHub Actions syntax"
build - Build system changes
git commit -m "build: update Turbo configuration"
git commit -m "build: add new package to monorepo"
revert - Revert previous commit
git commit -m "revert: revert 'feat: add feature X'"
Available Scopes
Project-specific scopes:
- api: API service (apps/api)
- web: Web application (apps/web)
- admin: Admin application (apps/admin)
- docs: Documentation (apps/docs)
- database: Database package (packages/database)
- types: Types package (packages/types)
- ui: UI package (packages/ui)
- utils: Utils package (packages/utils)
- logos: Logos package (packages/logos)
- infra: Infrastructure (infra/)
- deps: Dependency updates
- release: Release-related changes
Commit Message Guidelines
Subject Line
✅ Good:
feat: add user authentication
fix: resolve memory leak in cache
chore: update Next.js to v16
❌ Bad:
feat: Add user authentication. # No period
Fix: resolve memory leak # Capitalized
added new feature # No type
Rules
- Imperative mood: Use "add" not "added" or "adds"
- Lowercase: Subject should be lowercase
- No period: Don't end subject with period
- 50 chars max: Keep subject concise (72 chars absolute max)
- Be specific: Describe what changed, not how
Body
Use body for detailed explanation:
git commit -m "feat: add blog post generation
Implemented LLM-powered blog generation using Google Gemini.
Posts are automatically generated from car registration data
and published to the website.
Features:
- Gemini API integration
- Automated content generation
- Publishing workflow"
Footer
Use footer for breaking changes and issue references:
git commit -m "feat: redesign API authentication
BREAKING CHANGE: Authentication now requires JWT tokens
instead of API keys. Update clients to use new auth flow.
Closes #123
Refs #456"
Examples by Scenario
Adding a Feature
# Simple feature
git commit -m "feat(web): add dark mode toggle"
# Feature with scope
git commit -m "feat(api): add COE bidding data endpoint"
# Feature with body
git commit -m "feat(web): add interactive charts
Implemented interactive charts for car registration data
using Recharts library. Charts support filtering by make,
model, and date range."
Fixing a Bug
# Simple fix
git commit -m "fix(api): resolve database connection timeout"
# Fix with details
git commit -m "fix(web): fix chart rendering on mobile
Charts were not rendering correctly on mobile devices
due to incorrect responsive container configuration.
Updated chart components to use proper breakpoints."
# Critical fix
git commit -m "fix!: resolve security vulnerability in auth
BREAKING CHANGE: Auth tokens now require additional
signature verification. Clients must update to new SDK."
Updating Dependencies
# Single dependency
git commit -m "chore(deps): upgrade Next.js to v16"
# Multiple dependencies
git commit -m "chore(deps): update dependencies
- Next.js 15 → 16
- React 18 → 19
- Drizzle ORM 0.28 → 0.30"
# Security update
git commit -m "fix(deps): update vulnerable packages
Updated packages with known security vulnerabilities:
- axios 0.27.0 → 1.6.0 (CVE-2023-45857)
- express 4.17.1 → 4.18.2"
Refactoring
# Code refactoring
git commit -m "refactor(database): simplify migration logic"
# Extract component
git commit -m "refactor(web): extract reusable Button component"
# Rename
git commit -m "refactor(api): rename getCwd to getCurrentWorkingDirectory"
Documentation
# Update docs
git commit -m "docs: update deployment instructions"
# Add docs
git commit -m "docs(api): add API endpoint documentation"
# Fix typos
git commit -m "docs: fix typos in README"
Tests
# Add tests
git commit -m "test(api): add unit tests for auth service"
# Update tests
git commit -m "test(web): update E2E tests for new flow"
# Fix failing tests
git commit -m "test: fix flaky integration tests"
Chores
# Update config
git commit -m "chore: update TypeScript config"
# Clean up
git commit -m "chore: remove unused dependencies"
# Tooling
git commit -m "chore: add Biome configuration"
Version Bump Examples
Patch (0.0.x)
Bug fixes, no new features:
git commit -m "fix: resolve login error"
git commit -m "fix(web): fix broken link in navigation"
Minor (0.x.0)
New features, backwards compatible:
git commit -m "feat: add export to CSV functionality"
git commit -m "feat(api): add pagination to car data endpoint"
Major (x.0.0)
Breaking changes:
git commit -m "feat!: redesign API response format"
git commit -m "fix!: remove deprecated auth method
BREAKING CHANGE: API keys no longer supported.
Use JWT tokens for authentication."
Multi-Package Commits
When changes affect multiple packages:
# Scoped to main package
git commit -m "feat(web): add new dashboard page
Also updates:
- packages/ui: add new components
- packages/types: add dashboard types"
# No scope if truly cross-cutting
git commit -m "chore: update TypeScript to v5
Updates TypeScript across all packages to v5.0"
Breaking Changes
Explicit Breaking Change
git commit -m "feat!: change database schema
BREAKING CHANGE: User table renamed to users.
Run migration before deploying."
With Description
git commit -m "refactor!: redesign authentication
BREAKING CHANGE: Authentication flow completely redesigned.
Migration Guide:
1. Update auth tokens to JWT format
2. Replace getUser() with getCurrentUser()
3. Update middleware to use new auth context
Closes #234"
Issue References
Link commits to issues:
# Closes an issue
git commit -m "fix: resolve login timeout
Closes #123"
# References an issue
git commit -m "feat: add user profile page
Refs #456"
# Multiple issues
git commit -m "fix: resolve multiple auth bugs
Closes #123, #124, #125"
Commit Message Template
Create a commit template:
# ~/.gitmessage
# <type>(<scope>): <subject>
#
# <body>
#
# <footer>
#
# Types: feat, fix, docs, style, refactor, perf, test, chore
# Scopes: api, web, admin, docs, database, types, ui, utils, infra, deps
#
# Remember:
# - Use imperative mood (add, fix, update)
# - Keep subject under 50 characters
# - Separate subject from body with blank line
# - Wrap body at 72 characters
# - Use body to explain what and why, not how
# - Use footer for breaking changes and issue refs
Set as default:
git config --global commit.template ~/.gitmessage
Commitlint Configuration
The project uses commitlint to enforce rules:
// 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-enum": [
2,
"always",
[
"api",
"web",
"admin",
"docs",
"database",
"types",
"ui",
"utils",
"logos",
"infra",
"deps",
"release",
],
],
"subject-case": [2, "always", "lower-case"],
"subject-empty": [2, "never"],
"subject-full-stop": [2, "never", "."],
"header-max-length": [2, "always", 72],
},
};
Husky Integration
Commits are validated on commit:
# .husky/commit-msg
npx --no -- commitlint --edit $1
If commit fails:
git commit -m "bad commit"
# ✖ subject may not be empty [subject-empty]
# ✖ type may not be empty [type-empty]
Fix and retry:
git commit -m "feat: add new feature"
# ✔ Commit message passes validation
Amending Commits
Fix commit message:
# Amend last commit message
git commit --amend
# Amend without changing message
git commit --amend --no-edit
Viewing Commit History
# See recent commits
git log --oneline -10
# See commits with type
git log --oneline --grep="^feat"
git log --oneline --grep="^fix"
# See commits for specific scope
git log --oneline --grep="(web)"
git log --oneline --grep="(api)"
Semantic Release
The project uses semantic-release to automatically:
- Determine version bump based on commits
- Generate changelog
- Create git tag
- Publish release
Commit types → Version bump:
feat:→ Minor (0.x.0)fix:→ Patch (0.0.x)feat!:orBREAKING CHANGE:→ Major (x.0.0)- Other types → No bump
Quick Reference
# New feature
feat: <description>
feat(<scope>): <description>
# Bug fix
fix: <description>
fix(<scope>): <description>
# Breaking change
feat!: <description>
fix!: <description>
# No version bump
chore: <description>
docs: <description>
refactor: <description>
test: <description>
style: <description>
# With body and footer
type(scope): subject
Detailed explanation here
BREAKING CHANGE: Description
Closes #123
Troubleshooting
Commit Rejected
Error: subject may not be empty
Fix: Add subject after colon
git commit -m "feat: add user login"
Error: type may not be empty
Fix: Add valid type
git commit -m "feat: add feature"
Error: scope must be one of [...]
Fix: Use valid scope or omit
git commit -m "feat(api): add endpoint"
# or
git commit -m "feat: add endpoint"
Error: header must not be longer than 72 characters
Fix: Shorten subject, use body for details
git commit -m "feat: add feature
Detailed explanation goes in body, not subject line"
References
- Conventional Commits: https://www.conventionalcommits.org
- Commitlint: https://commitlint.js.org
- Semantic Release: https://semantic-release.gitbook.io
- Related files:
commitlint.config.js- Commitlint configuration- Root CLAUDE.md - Commit message guidelines
Best Practices
- Clear Subjects: Write clear, concise subjects
- Proper Types: Use correct type for the change
- Scopes: Add scope when change is package-specific
- Breaking Changes: Mark breaking changes explicitly
- Issue Links: Reference issues in footer
- Imperative Mood: Use "add" not "added"
- Lowercase: Keep subject lowercase
- No Period: Don't end subject with period