tomevault-io Commit Message Standards
Language: English | 繁體中文
Version: 1.0.0 Last Updated: 2025-12-24 Applicability: Claude Code Skills
Core Standard: This skill implements Commit Message Guide. For comprehensive methodology documentation, refer to the core standard.
Purpose
This skill ensures consistent, meaningful commit messages following conventional commits.
Quick Reference
Basic Format
<type>(<scope>): <subject>
<body>
<footer>
Commit Types
| English | When to Use |
|---|---|
feat |
New feature |
fix |
Bug fix |
refactor |
Code refactoring (no functional change) |
docs |
Documentation only |
style |
Formatting (no code logic change) |
test |
Adding or updating tests |
perf |
Performance improvement |
build |
Build system or dependencies |
ci |
CI/CD pipeline changes |
chore |
Maintenance tasks |
revert |
Revert previous commit |
security |
Security vulnerability fix |
Subject Line Rules
- Length: ≤72 characters (50 ideal)
- Tense: Imperative mood ("Add feature" not "Added feature")
- Capitalization: First letter capitalized
- No period: Don't end with a period
Detailed Guidelines
For complete standards, see:
AI-Optimized Format (Token-Efficient)
For AI assistants, use the YAML format files for reduced token usage:
- Base standard:
ai/standards/commit-message.ai.yaml - Language options:
- English:
ai/options/commit-message/english.ai.yaml - Traditional Chinese:
ai/options/commit-message/traditional-chinese.ai.yaml - Bilingual:
ai/options/commit-message/bilingual.ai.yaml
- English:
Examples
✅ Good Examples
feat(auth): Add OAuth2 Google login support
fix(api): Resolve memory leak in user session cache
refactor(database): Extract query builder to separate class
docs(readme): Update installation instructions for Node 20
❌ Bad Examples
fixed bug # Too vague, no scope
feat(auth): added google login # Past tense
Update stuff. # Period, vague
WIP # Not descriptive
Body Guidelines
Use the body to explain WHY the change was made:
fix(api): Resolve race condition in concurrent user updates
Why this occurred:
- Two simultaneous PUT requests could overwrite each other
- No optimistic locking implemented
What this fix does:
- Add version field to User model
- Return 409 Conflict if version mismatch
Fixes #789
Breaking Changes
Always document breaking changes in footer:
feat(api): Change user endpoint response format
BREAKING CHANGE: User API response format changed
Migration guide:
1. Update API clients to remove .data wrapper
2. Use created_at instead of createdAt
Issue References
Closes #123 # Automatically closes issue
Fixes #456 # Automatically closes issue
Refs #789 # Links without closing
Language Selection Decision (YAML Compressed)
# === LANGUAGE DECISION MATRIX ===
decision_tree:
- q: "Open source project?"
y: "→ English (international contributors)"
n: next
- q: "International/distributed team?"
y: "→ English (common language)"
n: next
- q: "Single-language team?"
y: "→ Team's primary language OR English"
n: "→ Bilingual (subject:EN, body:local)"
recommendation_matrix:
open_source: {lang: English, reason: "international contributors"}
international_team: {lang: English, reason: "common language"}
local_team_EN: {lang: English, reason: "tool compatibility, career mobility"}
local_team_ZH: {lang: "繁體中文", reason: "clarity, team preference"}
mixed: {lang: Bilingual, reason: "best of both worlds"}
# === TOOL COMPATIBILITY ===
tool_support:
full_unicode:
- GitHub/GitLab/Bitbucket
- VS Code/JetBrains
- SourceTree/GitKraken
potential_issues:
- "Some CI/CD log viewers"
- "Legacy terminal encodings"
- "Email notifications (rare)"
# === FORMAT BY LANGUAGE ===
english:
types: [feat, fix, refactor, docs, style, test, perf, build, ci, chore, revert, security]
example: "feat(auth): add OAuth2 Google login support"
traditional_chinese:
types: [功能, 修復, 重構, 文件, 樣式, 測試, 效能, 建置, CI, 雜項, 回退, 安全]
example: "功能(認證): 新增 OAuth2 Google 登入支援"
bilingual:
format: "type(scope): English subject\n\n中文詳細說明"
example: |
feat(auth): add OAuth2 Google login
新增 Google OAuth2 登入功能
- 實作授權流程
- 處理 token 交換
Configuration Detection
This skill supports project-specific language configuration.
Detection Order
- Check
CONTRIBUTING.mdfor "Commit Message Language" section - If found, use the specified option (English / Traditional Chinese / Bilingual)
- If not found, default to English for maximum tool compatibility
First-Time Setup
If no configuration found and context is unclear:
- Ask the user: "This project hasn't configured commit message language preference. Which option would you like to use? (English / 中文 / Bilingual)"
- After user selection, suggest documenting in
CONTRIBUTING.md:
## Commit Message Language
This project uses **[chosen option]** commit types.
<!-- Options: English | Traditional Chinese | Bilingual -->
Configuration Example
In project's CONTRIBUTING.md:
## Commit Message Language
This project uses **English** commit types.
### Allowed Types
feat, fix, refactor, docs, style, test, perf, build, ci, chore, revert, security
Related Standards
Version History
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
License
This skill is released under CC BY 4.0.
Source: universal-dev-standards
Converted and distributed by TomeVault — claim your Tome and manage your conversions.