303 lines
6.0 KiB
Markdown
303 lines
6.0 KiB
Markdown
# Git 工作流程規範
|
|
|
|
## 🌳 分支策略
|
|
|
|
### 主要分支
|
|
```
|
|
main (production)
|
|
├── develop (開發整合)
|
|
│ ├── feature/[feature-name]
|
|
│ ├── fix/[bug-description]
|
|
│ └── refactor/[component-name]
|
|
└── hotfix/[urgent-fix]
|
|
```
|
|
|
|
### 分支說明
|
|
|
|
| 分支類型 | 命名規則 | 用途 | 合併目標 |
|
|
|---------|---------|------|---------|
|
|
| `main` | main | 生產環境代碼 | - |
|
|
| `develop` | develop | 開發整合分支 | main |
|
|
| `feature/*` | feature/user-auth | 新功能開發 | develop |
|
|
| `fix/*` | fix/login-error | Bug 修復 | develop |
|
|
| `refactor/*` | refactor/api-structure | 代碼重構 | develop |
|
|
| `hotfix/*` | hotfix/critical-bug | 緊急修復 | main + develop |
|
|
|
|
## 📝 Commit 規範
|
|
|
|
### Commit Message 格式
|
|
```
|
|
<type>(<scope>): <subject>
|
|
|
|
<body>
|
|
|
|
<footer>
|
|
```
|
|
|
|
### Type 類型
|
|
- `feat`: 新功能
|
|
- `fix`: Bug 修復
|
|
- `docs`: 文檔更新
|
|
- `style`: 代碼格式（不影響功能）
|
|
- `refactor`: 重構
|
|
- `perf`: 性能優化
|
|
- `test`: 測試相關
|
|
- `chore`: 構建過程或輔助工具的變動
|
|
- `revert`: 回退
|
|
|
|
### 範例
|
|
```bash
|
|
feat(auth): add Google OAuth login
|
|
|
|
- Implement Google OAuth provider
|
|
- Add login button component
|
|
- Update auth configuration
|
|
|
|
Closes #123
|
|
```
|
|
|
|
### Commit 指令範例
|
|
```bash
|
|
# 功能開發
|
|
git commit -m "feat(flashcard): add AI generation feature"
|
|
|
|
# Bug 修復
|
|
git commit -m "fix(auth): resolve token expiration issue"
|
|
|
|
# 文檔更新
|
|
git commit -m "docs(api): update endpoint documentation"
|
|
|
|
# 代碼重構
|
|
git commit -m "refactor(components): extract reusable card component"
|
|
|
|
# 性能優化
|
|
git commit -m "perf(api): optimize database queries"
|
|
```
|
|
|
|
## 🔄 開發流程
|
|
|
|
### 1. 開始新功能
|
|
```bash
|
|
# 從 develop 創建新分支
|
|
git checkout develop
|
|
git pull origin develop
|
|
git checkout -b feature/flashcard-generation
|
|
|
|
# 開發過程中定期提交
|
|
git add .
|
|
git commit -m "feat(flashcard): implement basic structure"
|
|
```
|
|
|
|
### 2. 完成功能並提交 PR
|
|
```bash
|
|
# 推送分支
|
|
git push origin feature/flashcard-generation
|
|
|
|
# 在 GitHub 上創建 Pull Request
|
|
# PR 標題: [Feature] Flashcard Generation
|
|
# PR 描述: 詳細說明功能內容和測試方式
|
|
```
|
|
|
|
### 3. Code Review 流程
|
|
- 至少需要 1 位 reviewer 審核
|
|
- 通過所有自動化測試
|
|
- 解決所有 review comments
|
|
- 確認無衝突後合併
|
|
|
|
### 4. 合併後清理
|
|
```bash
|
|
# 刪除本地分支
|
|
git branch -d feature/flashcard-generation
|
|
|
|
# 刪除遠端分支
|
|
git push origin --delete feature/flashcard-generation
|
|
```
|
|
|
|
## 🚀 發布流程
|
|
|
|
### 1. 準備發布
|
|
```bash
|
|
# 從 develop 合併到 main
|
|
git checkout main
|
|
git pull origin main
|
|
git merge --no-ff develop
|
|
git tag -a v1.0.0 -m "Release version 1.0.0"
|
|
git push origin main --tags
|
|
```
|
|
|
|
### 2. 熱修復流程
|
|
```bash
|
|
# 從 main 創建 hotfix
|
|
git checkout main
|
|
git checkout -b hotfix/critical-error
|
|
|
|
# 修復並提交
|
|
git commit -m "fix: resolve critical production error"
|
|
|
|
# 合併回 main 和 develop
|
|
git checkout main
|
|
git merge --no-ff hotfix/critical-error
|
|
git checkout develop
|
|
git merge --no-ff hotfix/critical-error
|
|
|
|
# 清理分支
|
|
git branch -d hotfix/critical-error
|
|
```
|
|
|
|
## 📋 PR 模板
|
|
|
|
創建 `.github/pull_request_template.md`:
|
|
|
|
```markdown
|
|
## 📋 描述
|
|
簡要描述這個 PR 的內容
|
|
|
|
## 🎯 類型
|
|
- [ ] 🚀 新功能 (Feature)
|
|
- [ ] 🐛 Bug 修復 (Bugfix)
|
|
- [ ] 📝 文檔 (Documentation)
|
|
- [ ] 🎨 樣式 (Styling)
|
|
- [ ] 🔧 重構 (Refactoring)
|
|
- [ ] ⚡ 性能優化 (Performance)
|
|
- [ ] ✅ 測試 (Test)
|
|
- [ ] 🔨 構建 (Build)
|
|
- [ ] 🔄 CI/CD (CI)
|
|
- [ ] ⏪ 回退 (Revert)
|
|
|
|
## 🔗 相關 Issue
|
|
Closes #(issue number)
|
|
|
|
## ✅ 檢查清單
|
|
- [ ] 代碼已自測
|
|
- [ ] 已添加/更新測試
|
|
- [ ] 已更新相關文檔
|
|
- [ ] 符合代碼規範
|
|
- [ ] 無 TypeScript 錯誤
|
|
- [ ] 已在本地測試
|
|
|
|
## 📸 截圖（如適用）
|
|
如有 UI 變更，請附上截圖
|
|
|
|
## 📝 測試步驟
|
|
1. 步驟一
|
|
2. 步驟二
|
|
3. 預期結果
|
|
|
|
## 💬 備註
|
|
其他需要說明的內容
|
|
```
|
|
|
|
## 🛡️ 保護規則
|
|
|
|
### Main 分支保護
|
|
- 禁止直接推送
|
|
- 需要 PR review
|
|
- 需要通過 CI/CD 測試
|
|
- 需要最新的 develop 分支
|
|
|
|
### Develop 分支保護
|
|
- 需要 PR review
|
|
- 需要通過測試
|
|
- 自動刪除已合併的分支
|
|
|
|
## 📊 Git 常用命令
|
|
|
|
### 日常操作
|
|
```bash
|
|
# 查看狀態
|
|
git status
|
|
|
|
# 查看差異
|
|
git diff
|
|
git diff --staged
|
|
|
|
# 查看歷史
|
|
git log --oneline --graph --all
|
|
|
|
# 暫存當前工作
|
|
git stash
|
|
git stash pop
|
|
|
|
# 修改最後一次提交
|
|
git commit --amend
|
|
|
|
# 交互式重新整理提交
|
|
git rebase -i HEAD~3
|
|
```
|
|
|
|
### 分支操作
|
|
```bash
|
|
# 查看所有分支
|
|
git branch -a
|
|
|
|
# 切換分支
|
|
git checkout branch-name
|
|
git switch branch-name # Git 2.23+
|
|
|
|
# 創建並切換
|
|
git checkout -b new-branch
|
|
git switch -c new-branch # Git 2.23+
|
|
|
|
# 合併分支
|
|
git merge branch-name
|
|
git merge --no-ff branch-name # 保留合併記錄
|
|
|
|
# 刪除分支
|
|
git branch -d branch-name # 本地
|
|
git push origin --delete branch-name # 遠端
|
|
```
|
|
|
|
### 同步操作
|
|
```bash
|
|
# 獲取最新代碼
|
|
git fetch origin
|
|
git pull origin branch-name
|
|
|
|
# 推送代碼
|
|
git push origin branch-name
|
|
|
|
# 強制推送（謹慎使用）
|
|
git push --force-with-lease origin branch-name
|
|
```
|
|
|
|
## 🚨 緊急情況處理
|
|
|
|
### 回退提交
|
|
```bash
|
|
# 回退但保留修改
|
|
git reset --soft HEAD~1
|
|
|
|
# 回退並放棄修改
|
|
git reset --hard HEAD~1
|
|
|
|
# 創建回退提交
|
|
git revert HEAD
|
|
```
|
|
|
|
### 解決衝突
|
|
```bash
|
|
# 合併時遇到衝突
|
|
git status # 查看衝突文件
|
|
# 手動編輯解決衝突
|
|
git add .
|
|
git commit -m "resolve: merge conflicts"
|
|
```
|
|
|
|
### 恢復誤刪
|
|
```bash
|
|
# 查看 reflog
|
|
git reflog
|
|
|
|
# 恢復到特定提交
|
|
git reset --hard HEAD@{2}
|
|
```
|
|
|
|
## 📚 最佳實踐
|
|
|
|
1. **頻繁提交**：小步快跑，每個提交只做一件事
|
|
2. **寫好 Commit Message**：清晰描述做了什麼和為什麼
|
|
3. **定期同步**：每天開始工作前先 pull 最新代碼
|
|
4. **Code Review**：認真審核他人代碼，虛心接受建議
|
|
5. **保持分支簡潔**：完成後及時刪除無用分支
|
|
6. **測試後再提交**：確保代碼可運行再推送
|
|
7. **使用 .gitignore**：不要提交無關文件 |