Conventional Commits

Scope

The scope provides additional contextual information:

• feat(auth): add OAuth2 login - Scope: auth
• fix(api): resolve timeout - Scope: api
• docs(readme): update setup - Scope: readme

Scopes are project-specific. Common scopes:

• Frontend: ui, components, styles, assets
• Backend: api, db, auth, services
• DevOps: build, ci, deploy, infrastructure
• Project-specific: Module names, feature names

Description

Rules:

• Use imperative mood ("add" not "added" or "adds")
• No period at the end
• Lowercase first letter
• Concise but descriptive
• Limit to 50 characters (soft limit)

Good:

• feat(auth): add OAuth2 login flow
• fix(api): resolve request timeout
• docs(readme): update installation steps

Bad:

• feat(auth): Added OAuth2 login flow. (Wrong mood, has period)
• fix(api): fix the thing that broke (Too vague)
• feat: implement a very long description that exceeds reasonable limits (Too long)

Body

Purpose: Provide detailed explanation of WHAT and WHY

Rules:

• One blank line after subject
• Wrap at 72 characters
• Explain WHAT and WHY, not HOW
• Use imperative mood

Example:

feat(auth): add OAuth2 login flow

Implement OAuth2 authentication using Google provider.
This allows users to sign in with their Google account
instead of creating a separate password.

Closes #123

Footer

Purpose: Metadata about breaking changes and issue references

Breaking Changes:

feat(api): remove deprecated endpoint

BREAKING CHANGE: Endpoint /api/v1/users has been removed.
Use /api/v2/users instead.

Issue References:

fix(auth): resolve token expiration

Closes #456
Related #789
Fixes #123

Workflows

1. Writing Commit Messages

Step 1: Identify Type

# Did you add a new feature?
Type: feat

# Did you fix a bug?
Type: fix

# Did you change documentation?
Type: docs

# Other changes?
Type: chore, refactor, style, test, etc.

Step 2: Identify Scope

# What part of the codebase changed?
feat(auth):   # Authentication module
fix(api):     # API layer
docs(readme): # README file

Step 3: Write Description

# What did you do in 50 characters or less?
feat(auth): add OAuth2 login
fix(api): resolve timeout error
docs(readme): update setup guide

Step 4: Add Body (Optional)

feat(auth): add OAuth2 login

Implement OAuth2 authentication using Google provider.
This simplifies the login process and improves security.

Closes #123

2. Common Patterns

New Feature:

feat(feature-name): short description

Detailed explanation of what feature was added
and why it was necessary.

Closes #issue-number

Bug Fix:

fix(component-name): short description

Explanation of what was broken, why it broke,
and how it was fixed.

Fixes #issue-number

Breaking Change:

feat(component-name): short description

BREAKING CHANGE: Explanation of what broke and
how to migrate to the new version.

Documentation:

docs(file-name): short description

Updated documentation to reflect recent changes
in the codebase or clarify existing functionality.

Refactoring:

refactor(component-name): short description

Explanation of what was refactored and why.
No functional changes.

3. Validation Workflow

Before Committing:

# 1. Check commit message format
git log -1 --format=%s

# 2. Verify type is valid
# Should match: ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)

# 3. Check description length
# Should be <= 50 characters

# 4. Verify imperative mood
# Should use "add", "fix", "update" not "added", "fixed", "updated"

After Committing:

# 1. View commit message
git log -1 --format=fuller

# 2. Verify all parts are correct
# Type, scope, description, body, footer

Best Practices

✅ DO

• Use imperative mood: "add feature" not "added feature" or "adds feature"
• Keep description short: Under 50 characters
• Provide context in body: Explain WHY for significant changes
• Reference issues: Link commits to related issues
• Be consistent: Use the same types and scopes across the project
• Use scope for clarity: feat(auth): add login is better than feat: add login to auth module

❌ DON'T

• Don't mix types: feat and fix in the same commit
• Don't be vague: "update stuff" provides no value
• Don't add periods: No period at end of description
• Don't use past tense: "added feature" instead of "add feature"
• Don't forget breaking changes: Always mark breaking changes in footer
• Don't write novels: Keep subject under 50 characters

Examples

Example 1: Simple Feature

feat(auth): add OAuth2 login

Example 2: Bug Fix with Details

fix(api): resolve request timeout issue

The API was timing out when processing large payloads.
Added streaming response handling to prevent buffer overflow.

Fixes #456

Example 3: Breaking Change

feat(api): remove deprecated endpoints

BREAKING CHANGE: The following endpoints have been removed:
- /api/v1/users
- /api/v1/auth

Migrate to /api/v2/users and /api/v2/auth.

Migration guide: https://docs.example.com/migration-v2

Example 4: Documentation Update

docs(readme): update installation instructions

Added Docker installation method and updated
Python version requirements.

Related #789

Example 5: Refactoring

refactor(auth): simplify token validation

Consolidated token validation logic into a single function.
No functional changes - this improves code maintainability.

Refactored code is now 40% shorter and easier to understand.

Example 6: Performance Improvement

perf(db): optimize user query performance

Added database indexes for commonly queried fields.
Query performance improved from 500ms to 50ms.

Closes #123

Example 7: Test Addition

test(auth): add integration tests for OAuth2

Added comprehensive integration tests covering:
- Token generation
- Token refresh
- Token revocation
- Error handling

Troubleshooting

Issue: Commit message too long

Solution: Break into multiple commits or shorten description

# Too long
feat(auth): implement a very comprehensive OAuth2 login system with multiple providers

# Better
feat(auth): add OAuth2 multi-provider support

Issue: Wrong commit type selected

Solution: Use git commit --amend to fix before pushing

# Fix the commit message
git commit --amend -m "fix(auth): resolve token expiration"

# Push if you already pushed (requires force push)
git push --force-with-lease

Issue: Forgot to mark breaking change

Solution: Add footer to commit message

git commit --amend -m "feat(api): remove deprecated endpoint

BREAKING CHANGE: Endpoint /api/v1/users removed. Use /api/v2/users."

Integration with Git Hooks

Commit Message Linting

Add commitlint to enforce Conventional Commits:

Installation:

npm install -g @commitlint/cli @commitlint/config-conventional
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

Git Hook:

# .husky/pre-commit
#!/bin/sh
commitlint --edit $1

Commit Template

Set up a commit message template:

# Create template
cat > .gitmessage << 'EOF'
<type>(<scope>): <subject>

<body>

<footer>
EOF

# Configure git to use template
git config --global commit.template .gitmessage

Changelog Generation

Conventional Commits enable automatic changelog generation:

Using conventional-changelog:

npm install -g conventional-changelog-cli

# Generate changelog
conventional-changelog -p angular -i CHANGELOG.md -s

Output:

## [1.0.0] - 2024-01-15

### Added
- **auth:** add OAuth2 login flow
- **api:** add user profile endpoint

### Fixed
- **api:** resolve request timeout issue
- **ui:** fix mobile responsive layout

### Breaking Changes
- **api:** removed deprecated /api/v1/users endpoint

Tips

• Start with type: Think "Is this a feat, fix, docs, or chore?"
• Be specific: feat(auth): add login is better than feat: add stuff
• Write for humans: Other developers read commit messages
• Include WHY: Body should explain why, not how
• Link issues: Always reference related issue numbers
• Keep it simple: Most commits don't need a body
• Consistency matters: Use the same scopes across the project

Resources

Sources:

• Conventional Commits Specification
• Angular Commit Convention
• commitlint Documentation
• conventional-changelog Documentation
• How to Write a Git Commit Message
• Awesome Conventional Commits