Submit message writing specifications

The Importance of Commit Message Standards

Good commit messages help teams understand the intent and history of code changes. A clear commit history makes code reviews, issue tracking, and version rollbacks more efficient. Poorly written commit messages increase maintenance costs and reduce collaboration efficiency.

Basic Structure of a Commit Message

A standard commit message consists of three parts: a subject line, a body, and a footer. The subject line is a brief description, the body explains the reasons and details of the change, and the footer contains references or metadata.

fix: Fix user login failure issue  

When a user's password contains special characters, the backend API returns a 500 error.  
Modified the password validation logic to properly handle special characters.  

Closes #123  

Subject Line Guidelines

• Keep the subject line under 50 characters.
• Use imperative present tense (e.g., "fix" instead of "fixed").
• The first word should be lowercase, and no period at the end.
• Common prefixes include:
  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code formatting adjustments
  • refactor: Code refactoring
  • test: Test-related changes
  • chore: Build process or tooling changes

Bad Examples:

Fixed the bug  # Past tense  
User module optimization  # Missing type prefix  

Writing the Body

• Keep each line under 72 characters.
• Explain why the change was made rather than just what was changed.
• Describe the motivation and contrast with previous behavior.
• For complex changes, use bullet points:

feat: Add bulk delete for shopping cart  

- Users can now select multiple items for deletion  
- Added "Select All / Deselect All" checkbox  
- Backend API now supports `/cart/items/batch`  
- Added a confirmation dialog to prevent accidental deletion  

Previously, users could only delete items one by one, requiring multiple requests.  
During sales events, users reported inefficiency in managing their carts.  

Footer Format

The footer includes issue tracking, breaking changes, or co-author information. Use keywords to reference issues:

BREAKING CHANGE: Configuration file structure refactored; update `.env`  
See also: #45, #78  
Co-authored-by: John <john@example.com>  

Handling Special Cases

Multiple Related Commits

For large features split into multiple commits, note dependencies in the body:

refactor: User module data layer refactor (1/3)  

First part of the user module refactor, including:  
- Extracted database access logic  
- Unified error handling  

Upcoming commits:  
2/3: Business logic layer updates  
3/3: API interface modifications  

Hotfixes

For urgent fixes, indicate priority:

fix: Hotfix for payment timeout issue [P0]  

Payment gateway timeout misconfiguration caused order failures.  
Reverted to 30-second timeout as an immediate fix.  

Root cause: Deployment script overwrote config  

Recommended Automation Tools

Use commitlint to enforce message standards:

// commitlint.config.js  
module.exports = {  
  extends: ['@commitlint/config-conventional'],  
  rules: {  
    'header-max-length': [2, 'always', 72],  
    'body-max-line-length': [2, 'always', 72]  
  }  
}  

Add Git hooks with husky:

// package.json  
{  
  "husky": {  
    "hooks": {  
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"  
    }  
  }  
}  

Team Collaboration Tips

1. Train new members on commit standards.
2. Review commit messages during code reviews.
3. Regularly clean up commit history (e.g., squash minor commits).
4. Use feature branches and PRs for complex changes.

Example of a Bad Commit & Improvement:

// Bad  
Fixed something  

// Improved  
fix: Resolve homepage image flickering  

Chrome's lazy loading caused layout shifts.  
Added explicit width/height attributes and switched to IntersectionObserver.  

Fixes #326  

Commit Messages & Version Releases

Well-structured commits enable automated changelog generation:

# Generate changes between versions  
git log v1.0.0..v1.1.0 --pretty=format:"- %s (%h)" --no-merges  

Semantic Versioning (SemVer) based on commit types:

• feat → Minor version bump
• fix → Patch version bump
• BREAKING CHANGE → Major version bump

Amending Commit History

Edit the last commit message:

git commit --amend  

Interactive rebase for multiple commits:

git rebase -i HEAD~3  
# Replace "pick" with "reword"  

Enterprise Practices

Large-scale project template:

type(module): Short description [JIRA-ID]  

Details and impact:  

- Specific change 1  
- Specific change 2  

Testing steps:  
1. Test scenario 1  
2. Test scenario 2  

References:  
- Design doc link  
- API doc link  

BREAKING CHANGE: Incompatible changes  

Multilingual Projects

For non-English teams, consider bilingual messages:

fix(login): 修复验证码发送限制问题 [Fix SMS limit]  

验证码接口未做频率限制导致被恶意调用。  
Added rate limiting (10 requests/hour) to /api/sms.  

Changes:  
- Added Redis counter  
- Returns HTTP 429  
- Logs security events  

Security: MEDIUM