Conventional Commits: A Comprehensive Guide

January 22, 2025 (1y ago) · 4 min read

Open Source

Originally published on LinkedIn, 22 January 2025. Republished here with light editing.

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

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.

LinkedIn