Imported from Athena-Git-Group/athena-plugin-dev (skills/git-conventions/SKILL.md). Install upstream with npx skills add Athena-Git-Group/athena-plugin-dev --skill git-conventions. Copyright stays with the author.

Git Conventions

Git 分支命名與 Commit Message 規範，確保團隊協作的一致性與可追溯性。

When to Use

• 建立新分支 - 使用標準分支命名格式
• 撰寫 commit message - 使用標準 commit 格式
• Code review - 檢查分支和 commit 是否符合規範

Branch Naming

Format

<type>/<source>_<description>
<type>/<source>_hap<ticket>_<description>

Branch Types

Source Branch

來源分支標示此分支從哪裡切出：

Naming Rules

1. 全部小寫 - 使用小寫字母
2. 底線分隔 - 描述部分使用 _ 分隔
3. 簡潔明瞭 - 描述應簡短但能表達意圖
4. Ticket 可選 - HAP ticket 號碼為可選，有則加入

Examples

# 有 HAP ticket
git checkout -b feature/main_hap3621_member_export
git checkout -b bugfix/develop_hap3449_tier_calculation
git checkout -b hotfix/main_hap5678_fix_critical_bug
git checkout -b refactor/main_hap3600_cleanup_service

# 無 HAP ticket
git checkout -b feature/develop_member_export
git checkout -b bugfix/develop_fix_null_pointer
git checkout -b hotfix/main_fix_payment_error
git checkout -b refactor/main_cleanup_legacy_code

# 版本升級（v2 變體）
git checkout -b feature/main_hap3621_member_export_v2

Commit Convention

Format

# 分支有 HAP ticket 時
[HAP-XXXX] type(scope): 簡述

# 分支無 HAP ticket 時
type(scope): 簡述

Commit Types

Scope Guidelines

Scope 應反映變更的模組或領域：

Commit Message Rules

1. 簡述用祈使句 - 使用動詞開頭（add, fix, update, remove）
2. 簡述限制 50 字元 - 保持簡潔
3. 首字母小寫 - type 後的簡述首字母小寫
4. 不加句號 - 簡述結尾不加標點符號
5. 語言偏好 - 簡述可使用用戶配置的語言

Language Support

參考 references/output-language.md 以取得用戶語言偏好：

# 使用共用 script 讀取語言設定（優先順序：Local > Project > User）
OUTPUT_LANG=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/get_athena_setting.py" athena language --default "English")

Commit message 的簡述可依語言偏好撰寫：

# 英文（預設）
git commit -m "[HAP-3621] feat(member): add member export API"

# 繁體中文
git commit -m "[HAP-3621] feat(member): 新增會員匯出 API"

# 日文
git commit -m "[HAP-3621] feat(member): メンバーエクスポートAPIを追加"

注意：type 和 scope 保持英文，僅簡述部分可使用其他語言。

Examples

# === 分支有 HAP ticket 時 ===
git commit -m "[HAP-3621] feat(member): add member export API"
git commit -m "[HAP-3449] fix(tier): correct upgrade calculation logic"
git commit -m "[HAP-3600] refactor(service): extract common validation"

# === 分支無 HAP ticket 時 ===
git commit -m "feat(member): add member export API"
git commit -m "fix(tier): correct upgrade calculation logic"
git commit -m "refactor(service): extract common validation"
git commit -m "docs(readme): update changelog for v1.2.4"
git commit -m "chore: bump version to 1.2.4"

Ticket Number Inference

從分支名稱自動擷取

當前分支格式為 <type>/<source>_hap<ticket>_<description> 時，可自動推斷 ticket 號碼：

# 取得當前分支
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# 擷取 ticket 號碼
TICKET=$(echo "$BRANCH" | grep -oP '(?<=hap)\d+' | head -1)

# 格式化為 commit prefix
PREFIX="[HAP-${TICKET}]"

範例推斷

Quick Reference

Create Feature Branch

建立分支前必須先同步遠端 base 分支，確保從最新版本開始開發：

# 1. 切換到 base 分支（通常是 main 或 develop）
git checkout main

# 2. 同步遠端最新變更
git pull origin main

# 3. 建立新分支
git checkout -b feature/main_hap<TICKET>_<description>

單行版本（適合熟練使用者）：

git fetch origin main && git checkout -b feature/main_hap<TICKET>_<description> origin/main

為什麼要先同步？

• 避免基於過時程式碼開發，減少後續合併衝突
• 確保包含其他人已合併的變更
• 保持分支歷史乾淨

Commit with Convention

git commit -m "[HAP-<TICKET>] <type>(<scope>): <description>"

Full Workflow Example

# 1. 同步遠端 base 分支
git checkout main
git pull origin main

# 2. 建立功能分支
git checkout -b feature/main_hap3621_member_export

# 3. 開發並提交
git add .
git commit -m "[HAP-3621] feat(member): add member export API"

# 4. 追加提交
git commit -m "[HAP-3621] test(member): add export unit tests"
git commit -m "[HAP-3621] docs(api): document export endpoint"

# 5. 推送前再次同步（可選，減少 PR 衝突）
git fetch origin main
git rebase origin/main  # 或 git merge origin/main

Validation Checklist

Branch Name

• 使用正確的 type (feature/, bugfix/, hotfix/, refactor/, chore/)
• 包含來源分支 (main, master, release, develop)
• 若有 HAP ticket，格式為 hap<number>_
• 描述簡潔明瞭
• 全部小寫

Commit Message

• 若分支有 HAP，包含 [HAP-XXXX] prefix
• 使用正確的 type (feat, fix, docs, refactor, test, chore)
• 包含有意義的 scope
• 簡述使用祈使句
• 簡述首字母小寫

Version History