- 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
[optional scope]: [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 bob@example.com 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
.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