Commit Conventions

Standardized commit message formats for clear, searchable Git history.

Conventional Commits Format

Use Conventional Commits for clear, searchable commit history.

Conventional Commit Structure

type(scope): description

[optional body]

[optional footer(s)]

Benefits of Conventional Commits

• Automated Versioning: Tools can determine semantic version bumps
• Generated Changelogs: Automatically create release notes
• Better Navigation: Easily filter commits by type
• Clear Communication: Standardized format aids understanding

Commit Types

Use these standardized types to categorize your changes:

✨ feat

New feature for the user

🐛 fix

Bug fix for the user

📚 docs

Changes to documentation

💄 style

Formatting, missing semicolons, etc.

♻️ refactor

Code change that neither fixes a bug nor adds a feature

✅ test

Adding missing tests

🔧 chore

Changes to build process or auxiliary tools

⚡ perf

Performance improvements

Good Commit Examples

Well-Written Commits

# Feature commits
feat(auth): add OAuth2 Google authentication
feat(api): implement user profile endpoints
feat(ui): add dark mode toggle component

# Bug fixes
fix(auth): resolve token expiration handling
fix(api): correct validation error messages
fix(ui): fix responsive layout on mobile devices

# Documentation
docs(readme): update installation instructions
docs(api): add authentication endpoint examples

# Refactoring
refactor(auth): extract validation logic to separate module
refactor(api): simplify error handling middleware

# Breaking changes
feat(api)!: change user endpoint response format

BREAKING CHANGE: user endpoint now returns nested user object

# With scope and body
feat(dashboard): add user statistics widget

Add comprehensive user statistics including:
- Login frequency over time
- Feature usage analytics  
- Performance metrics

Closes #123

Poor Commit Examples

Commits to Avoid

# ❌ Too vague
fix: bug fix
update: changes
wip: stuff

# ❌ Too detailed for subject line
feat: add new user authentication system with OAuth2 Google integration and JWT token management plus password reset functionality

# ❌ Wrong type
feat: fix typo in documentation  # Should be docs:
fix: add new feature  # Should be feat:

# ❌ Poor grammar/formatting
Fix bug in the login system
added new feature
Update documentation

# ❌ Implementation details in subject
feat: change getUserData() function to return promise instead of callback

Common Mistakes to Avoid

• Using past tense ("Added" instead of "Add")
• Capitalizing the first word of description
• Adding periods at the end of the subject line
• Being too vague about what changed
• Including implementation details in the subject

Scopes and Breaking Changes

Using Scopes

Scopes provide additional context about which part of the codebase was affected:

Scope Examples

# By component/module
feat(auth): add password reset functionality
fix(dashboard): correct chart data calculation
docs(api): update authentication endpoints

# By layer/area
feat(frontend): add loading spinners
fix(backend): resolve database connection timeout
test(integration): add user workflow tests

# By feature
feat(payments): integrate Stripe payment processing
fix(search): improve query performance

Breaking Changes

Mark breaking changes with ! and provide detailed explanation:

Breaking Change Examples

# Using ! notation
feat(api)!: change user response format

BREAKING CHANGE: The user endpoint now returns a nested user object
instead of a flat structure. Update client code to access user.profile.name
instead of user.name.

# Multiple breaking changes
refactor(auth)!: redesign authentication system

BREAKING CHANGES:
- Remove deprecated login() method, use authenticate() instead
- Change token format from JWT to custom format  
- Require email verification before account activation

← Gitflow Workflow Squash & Merge →