Conventional Commits: A Comprehensive Guide

I. Introduction to Conventional Commits

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. This standardization creates an explicit commit history that makes projects more maintainable and automates various development processes.

II. Basic Format

A standard commit message consists of the following structure:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Where:

• <type>: Indicates the type of change
• [optional scope]: Indicates the section of the codebase affected
• <description>: A brief description of the change
• [optional body]: Detailed explanation of the change
• [optional footer]: Place for breaking changes and issue references

III. Commit Types in Detail

1. feat (Features)

Used when adding new features.

Example:

feat(login): implement user authentication system

- Add phone number login
- Implement SMS verification
- Integrate WeChat OAuth

Related task: #123

2. fix (Bug Fixes)

Used when fixing a bug.

Example:

fix(database): resolve user data query timeout

Increased database connection timeout from 5s to 30s to resolve user data query failures during peak hours.

Fixes: #234

3. docs (Documentation)

Used for documentation updates.

Example:

docs(api): update API documentation

- Add documentation for new endpoints
- Update parameter descriptions
- Add code examples for API calls

4. style (Formatting)

Used for changes that don’t affect code functionality (formatting, spacing, semicolons, etc.).

Example:

style(components): standardize code indentation and spacing

- Implement 2-space indentation
- Adjust bracket line breaks
- Remove excessive blank lines

5. refactor (Code Restructuring)

Used for code changes that neither fix bugs nor add features.

Example:

refactor(utils): restructure date handling utilities

Consolidated all date-related functions into DateUtils class to improve code reusability and maintainability.

6. perf (Performance)

Used for performance improvements.

Example:

perf(images): optimize image loading performance

- Implement lazy loading
- Compress image sizes
- Add image caching mechanism

Performance improved by approximately 50%

7. test (Testing)

Used when adding or modifying tests.

Example:

test(auth): add unit tests for authentication module

- Add username/password login test cases
- Implement verification code validation tests
- Add login failure scenario tests

8. chore (Maintenance)

Used for changes to the build process or auxiliary tools.

Example:

chore(deps): update project dependencies

Upgrade React to 18.0.0
Update other dependencies to latest stable versions

IV. Scope Guidelines

Scope indicates the section of the codebase affected by the change, typically using project module names.

Common scope examples:

• ui: Interface-related
• api: API-related
• auth: Authentication-related
• database: Database-related
• utils: Utility-related

V. Writing Tips

1. Title Requirements

• Maximum 50 characters
• Start with a verb (add, fix, update, etc.)
• Be concise and clear
• No period at the end

2. Body Requirements

• Separate title from body with a blank line
• Wrap lines at 72 characters
• Explain the motivation for the change
• Compare with previous behavior
• Use bullet points for specific changes

3. Footer Requirements

Mainly used for:

• Breaking Changes
• Closing issues (e.g., Closes #123, #245)
• Other references

VI. Special Cases

1. Breaking Changes

When introducing breaking changes:

feat(api): restructure authentication endpoints

Replace JWT authentication with session-based mechanism

BREAKING CHANGE: Authentication endpoint now requires new header format

2. Multiple Types

When a commit involves multiple types, use the most significant type:

feat(user): implement profile editing with fixes

- Add avatar upload functionality
- Fix username modification bug
- Optimize form submission performance

VII. Commit Examples

1. New Feature Development

feat(order): implement order export functionality

- Add Excel export capability
- Support custom field selection
- Implement progress indication

Files affected:
- src/services/order.js
- src/components/OrderExport.vue
- src/utils/excel.js

Related task: #432

2. Bug Fix

fix(cart): resolve cart quantity update issue

Issue:
Item quantity not updating when clicking increase/decrease buttons

Solution:
Fixed quantity calculation logic and added UI refresh after data updates

Fixes: #345

3. Code Optimization

refactor(common): optimize common component structure

- Extract repeated code into standalone components
- Improve component prop handling
- Standardize error handling logic

Scope:
- src/components/common/*
- src/utils/error.js

VIII. Common Mistakes

1. Incorrect Commit Messages

# ❌ Bad Examples
update code
fix bug
adjust style

2. Correct Commit Messages

# ✅ Good Examples
feat(home): add homepage carousel component
fix(login): resolve unresponsive login button
style(global): standardize button styling

IX. Useful Tools

1. commitlint: Checks if commit messages meet the conventional commit format
2. commitizen: Interactive CLI tool for generating conventional commits
3. conventional-changelog: Automatically generates changelogs from conventional commit messages

X. Best Practices

1. Establish commit conventions at project inception
2. Configure git hooks to enforce commit message standards
3. Regularly review commit history and correct non-compliant commits
4. Ensure team-wide understanding through training

This guide serves as a comprehensive reference for teams looking to implement or improve their commit message practices. Following these conventions leads to clearer communication, easier maintenance, and more efficient development processes.