# Conventional Commits: A Comprehensive Guide > A reference for the Conventional Commits specification: the message format, all eight commit types explained, scope guidelines, title/body/footer requirements, breaking changes, worked examples, and common mistakes. Source: https://chanmeng.org/blog/conventional-commits-guide Author: Chan Meng — https://chanmeng.org Published: 2025-01-22 Tags: 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: ``` [optional scope]: [optional body] [optional footer] ``` Where: - \: Indicates the type of change - \[optional scope]: Indicates the section of the codebase affected - \: 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.