Commit Message Standards

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

Subject Line Rules

1. Length: ≤72 characters (50 ideal)
2. Tense: Imperative mood ("Add feature" not "Added feature")
3. Capitalization: First letter capitalized
4. No period: Don't end with a period

Detailed Guidelines

For complete standards, see:

• Conventional Commits Guide
• Language Options

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

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

1. Check CONTRIBUTING.md for "Commit Message Language" section
2. If found, use the specified option (English / Traditional Chinese / Bilingual)
3. If not found, default to English for maximum tool compatibility

First-Time Setup

If no configuration found and context is unclear:

1. Ask the user: "This project hasn't configured commit message language preference. Which option would you like to use? (English / 中文 / Bilingual)"
2. 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

• Commit Message Guide
• Git Workflow
• Changelog Standards

---

Version History

---

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards