⚠️ 核心規則 - 開始任何工作前必讀

🚫 絕對禁止的操作

在開始任何程式碼修改前，必須先檢查目前分支！

# 檢查目前分支
git branch

# 如果在 main 分支，立即建立新分支
git checkout -b <type>/<name>/<description>

禁止清單

❌ 絕對不可以直接在 main 分支上修改檔案
❌ 不可以在 main 分支上執行 git add
❌ 不可以在 main 分支上執行 git commit
❌ 不可以在 main 分支上編輯、新增或刪除任何檔案

正確流程

✅ 先確認目前在 main 分支
✅ 建立新的功能分支
✅ 在功能分支上進行修改
✅ 提交到功能分支
✅ 透過 Pull Request 合併

我的功能

提供標準化的 Git 分支命名規範
確保分支類型、開發者名稱和功能描述的一致性
協助團隊遵循最佳的 Git 工作流程

何時使用我

在以下情況下使用此技能：

建立新的 Git 分支時
需要確認分支命名是否符合規範
團隊協作需要統一的分支管理策略
進行 code review 時檢查分支命名

分支命名規範

標準格式

<type>/<developer-name>/<feature-description>

分支類型 (type)

feat: 新功能開發
- 例如: feat/lip/user-authentication
- 用於: 開發全新的功能或特性
fix: 錯誤修復
- 例如: fix/lip/login-button-error
- 用於: 修復現有功能的 bug
refactor: 程式碼重構
- 例如: refactor/lip/optimize-state-management
- 用於: 改善程式碼結構，但不改變功能
docs: 文件更新
- 例如: docs/lip/update-readme
- 用於: 更新專案文件、README、註解等
style: 樣式調整
- 例如: style/lip/improve-button-design
- 用於: UI/UX 改進、CSS 調整
test: 測試相關
- 例如: test/lip/add-unit-tests
- 用於: 新增或修改測試
chore: 雜項任務
- 例如: chore/lip/update-dependencies
- 用於: 依賴更新、建置配置等

命名原則

使用小寫字母: 所有分支名稱使用小寫
使用連字符: 單詞之間使用 - 連接
簡潔明確: 功能描述應簡短但具描述性
英文命名: 統一使用英文命名
避免特殊字符: 只使用字母、數字和連字符

實際範例

# ✅ 正確範例
git checkout -b feat/lip/add-language-selector
git checkout -b fix/lip/fix-search-modal-crash
git checkout -b refactor/lip/improve-jotai-structure
git checkout -b docs/lip/update-api-documentation

# ❌ 錯誤範例
git checkout -b new-feature              # 缺少類型和開發者名稱
git checkout -b feat/AddFeature          # 使用大寫字母
git checkout -b feat/lip/新增功能     # 使用中文
git checkout -b feat-lip-feature      # 格式錯誤

工作流程

1. 建立新分支

# 從 main 分支建立新分支
git checkout main
git pull origin main
git checkout -b <type>/<name>/<description>

2. 開發過程

# 定期提交變更
git add .
git commit -m "feat: implement user authentication"

# 定期同步主分支
git fetch origin main
git rebase origin/main

3. 準備合併

# 推送分支到遠端
git push -u origin <branch-name>

# 建立 Pull Request
# 使用 GitHub/GitLab 介面建立 PR

4. 合併後清理

# 刪除本地分支
git branch -d <branch-name>

# 刪除遠端分支
git push origin --delete <branch-name>

提交訊息規範

格式

<type>: <subject>

<body>

<footer>

類型 (type)

與分支類型相同: feat, fix, refactor, docs, style, test, chore

⚠️ 重要：語言使用規範

預設使用繁體中文撰寫 commit message

除非有特別要求（如國際協作專案），否則 commit message 的 subject 和 body 都應該使用繁體中文撰寫。

原則

Type 使用英文: feat, fix, refactor 等類型標籤保持英文
Subject 使用中文: 主要描述使用繁體中文
Body 使用中文: 詳細說明使用繁體中文
Footer 依情況: issue 編號等可使用英文

範例

# ✅ 正確：使用中文
git commit -m "feat: 新增語言選擇器元件"

# ✅ 正確：詳細提交使用中文
git commit -m "feat: 新增語言選擇器元件

- 實作包含 5 種語言選項的下拉選單
- 新增語言設定持久化到 localStorage
- 更新 i18n 配置

Closes #123"

# ✅ 正確：修復 bug
git commit -m "fix: 修正登入按鈕點擊無反應的問題"

# ✅ 正確：重構程式碼
git commit -m "refactor: 重構 Jotai 狀態管理結構

- 拆分 dataAtoms 為多個模組
- 優化 atom 命名和組織
- 改善型別定義"

# ❌ 錯誤：使用英文（除非有特別要求）
git commit -m "feat: add language selector component"

# ❌ 錯誤：中英混用不當
git commit -m "feat: 新增 language selector 元件"

特殊情況

何時使用英文？

國際協作專案明確要求
開源專案的國際貢獻
團隊特別指定使用英文

如果不確定，預設使用中文。

注意事項

絕不直接在 main 分支開發: 永遠從 main 建立新分支
保持分支生命週期短: 盡快完成並合併分支
定期同步主分支: 避免合併衝突
使用有意義的名稱: 讓他人能理解分支目的
一個分支一個功能: 避免在單一分支混合多個不相關的變更

⚠️ 重要：測試與提交流程

每次修改後必須測試

這是強制性規則！任何程式碼修改都必須立即測試。

# 修改程式碼後，立即執行測試
lsof -ti:3000 | xargs kill -9 2>/dev/null
sleep 2
pnpm dev

檢查項目：

✅ 專案能否成功啟動
✅ 無編譯錯誤
✅ 功能正常運作
✅ 無執行錯誤

完成後的提交流程

⚠️ 絕不直接推送！必須等待使用者確認。

# 1. 提交到本地分支
git add .
git commit -m "type: description"

# 2. ⏸️ 停止！告知使用者已完成
# 說明：「修改已完成並測試通過，請檢查後再推送」

# 3. ⏸️ 等待使用者檢查確認

# 4. ✅ 使用者確認後才推送
git push origin branch-name

推送前最終檢查清單

錯誤示範 vs 正確示範

# ❌ 錯誤：直接推送
git add .
git commit -m "feat: add feature"
git push origin feature-branch  # 錯誤！未經確認就推送

# ✅ 正確：等待確認
git add .
git commit -m "feat: add feature"
# 告知使用者：「修改完成，已測試通過，請檢查」
# 等待使用者回覆確認
# 收到確認後才執行：
git push origin feature-branch

常見問題

Q: 如何處理長期開發的功能？

A: 建立 feature 分支，定期從 main rebase，完成後再合併。

Q: 可以在分支名稱中使用 issue 編號嗎？

A: 可以，格式: feat/ponpon/add-feature-#123

Q: 如何處理緊急修復？

A: 使用 hotfix 類型: hotfix/ponpon/critical-bug-fix

Q: 為什麼不能直接推送？

A: 使用者需要在本地環境檢查功能、測試效果、確認無誤後才能推送到遠端。這可以防止將問題程式碼推送到遠端儲存庫。

Q: 每次修改都要測試嗎？

A: 是的，絕對需要！任何程式碼修改（無論大小）都必須立即測試，確保沒有破壞現有功能。

git-workflow