Finishing a Development Branch · Superpowers

Finishing a Development Branch Skill

Finishing a Development Branch 是 Superpowers 中的重要完成型 skills，專注於系統化地完成開發分支的所有收尾工作，確保程式碼品質和整合順利進行。

何時使用

在以下情況中使用 Finishing a Development Branch skill：

✅ 必須使用的情境：

完成一個功能或重構的開發
準備將分支合併到主分支前
完成所有開發任務和測試
需要確保分支可安全合併
Sprint 結束需要整合功能

❌ 不適合的情境：

還在開發中的功能
只是中間的開發里程碑
需要先驗證功能（應先用 verification）
還有未完成的測試

完成分支的清單

第 1 層：功能完整性

確保所有承諾的功能都已實作：

功能驗收清單：
- [ ] 所有承諾的功能都已實作
- [ ] 所有邊界條件都已處理
- [ ] 錯誤處理完整且合理
- [ ] 功能符合需求文件的描述
- [ ] 使用者體驗符合預期

第 2 層：程式碼品質

確保程式碼符合品質標準：

程式碼品質清單：
- [ ] 程式碼符合專案的 linting 規則
- [ ] TypeScript 型別檢查無誤
- [ ] 程式碼可讀且命名清楚
- [ ] 複雜邏輯有適當註解
- [ ] 沒有除錯用的 console.log
- [ ] 沒有註解掉的程式碼
- [ ] 沒有無用的 import 和變數

第 3 層：測試覆蓋

確保有足夠的測試保護：

測試清單：
- [ ] 所有核心功能都有單元測試
- [ ] 關鍵路徑有整合測試
- [ ] 邊界條件有測試覆蓋
- [ ] 錯誤情況有測試處理
- [ ] 所有測試通過（100% pass rate）
- [ ] 測試覆蓋率符合專案標準

第 4 層：文件和註解

確保適當的文件說明：

文件清單：
- [ ] 複雜的函式有 JSDoc 註解
- [ ] API 變更已更新到 API 文件
- [ ] README 或使用文件已更新
- [ ] 變更日誌（CHANGELOG）已更新
- [ ] 重要設計決策有記錄

第 5 層：整合和相容性

確保與其他系統的整合：

整合清單：
- [ ] 與現有功能的相容性
- [ ] API 的向後相容性
- [ ] 資料庫 migration 正確
- [ ] 環境變數設定文件已更新
- [ ] 第三方服務整合正常

完成分支的流程

第 1 步：自我審查

在請求審查前先進行徹底的自我審查：

# 1. 檢查程式碼變更
git diff main...HEAD

# 2. 檢查檔案列表
git diff main...HEAD --name-only

# 3. 執行所有測試
npm test

# 4. 檢查型別
npm run type-check

# 5. 檢查 linting
npm run lint

# 6. 檢查建置
npm run build

第 2 步：最終驗證

使用 verification-before-completion skill 進行最終驗證：

驗證檢查：
✓ 功能正常運作
✓ 沒有 regression
✓ 效能符合預期
✓ 安全性檢查通過

第 3 步：清理程式碼

清理所有開發過程中的遺留物：

// 移除除錯程式碼
- console.log('debug:', data);  // ❌ 移除
- debugger;                      // ❌ 移除

// 移除註解掉的程式碼
- // const oldFunction = () => { ... };  // ❌ 移除

// 移除無用的 import
- import { unusedFunction } from './utils';  // ❌ 移除

// 移除 TODO 和 FIXME（除非有意義的）
// TODO: 優化效能  // ❌ 移除或建立 issue

第 4 步：更新文件

確保所有相關文件都已更新：

文件更新：
- [x] 更新 README.md（如果影響使用方式）
- [x] 更新 API.md（如果有 API 變更）
- [x] 更新 CHANGELOG.md（記錄重要變更）
- [x] 更新 migration guide（如果有 breaking changes）

第 5 步：提交最後變更

將所有收尾工作提交：

# 提交程式碼清理
git add .
git commit -m "chore: code cleanup and final polish"

# 如果有多個收尾 commit，可以 squash
git rebase -i HEAD~3

第 6 步：更新分支

確保分支與主分支同步：

# Fetch 最新的 main
git fetch origin main

# Rebase 到最新的 main（保持乾淨的歷史）
git rebase origin/main

# 如果有 conflict，解決後繼續
git rebase --continue

實際範例

範例 1：完成功能分支

情境：完成使用者認證功能的開發

完成流程：

# 第 1 步：檢查當前狀態
$ git status
On branch feature/user-auth
Your branch is ahead of 'origin/feature/user-auth' by 3 commits.

# 第 2 步：檢查程式碼品質
$ npm run lint
✓ All files pass linting

$ npm run type-check
✓ No type errors found

# 第 3 步：執行測試
$ npm test
PASS  src/auth/auth.test.ts
PASS  src/auth/login.test.ts
PASS  src/auth/register.test.ts
✓ All 23 tests passed

# 第 4 步：建置測試
$ npm run build
✓ Build successful

# 第 5 步：清理程式碼
# 移除所有 console.log 和除錯程式碼
$ git add -A
$ git commit -m "chore: remove debug code and finalize implementation"

# 第 6 步：更新文件
# 更新 README、API 文件、CHANGELOG
$ git commit -m "docs: update documentation for auth feature"

# 第 7 步：同步 main 分支
$ git fetch origin main
$ git rebase origin/main
Current branch feature/user-auth is up to date.

# 第 8 步：推送到遠端
$ git push origin feature/user-auth

# 第 9 步：建立 Pull Request
# 在 GitHub 上建立 PR 並填寫完整描述

PR 描述：

## 實作使用者認證功能

### 變更摘要
完整的認證系統，包含註冊、登入、登出和 session 管理。

### 功能清單
- ✅ Email 註冊功能
- ✅ 密碼登入功能
- ✅ Session 管理
- ✅ 自動登出機制
- ✅ 密碼重置功能

### 技術實作
- **後端**：Express.js + JWT + bcrypt
- **前端**：React Context API
- **資料庫**：PostgreSQL（含 migration）
- **測試**：Jest + Supertest

### 測試狀態
- ✅ 單元測試：18 個測試全部通過
- ✅ 整合測試：5 個測試全部通過
- ✅ 測試覆蓋率：87%

### 程式碼品質
- ✅ Linting 通過
- ✅ TypeScript 無錯誤
- ✅ 無 console.log 或除錯程式碼
- ✅ 程式碼已格式化

### 文件
- ✅ README 已更新
- ✅ API 文件已更新
- ✅ CHANGELOG 已更新
- ✅ Migration guide 已建立

### 測試部署
- ✅ 已部署到測試環境
- ✅ 功能測試通過
- ✅ 效能測試通過

### 截圖
（附上功能截圖）

### 相關 Issue
Closes #123, #124

### 待審查項目
請特別關注：
1. 認證邏輯的正確性
2. Session 管理的安全性
3. 錯誤處理的完整性

範例 2：處理合併衝突

情境：在 rebase 時遇到衝突

處理流程：

# 第 1 步：開始 rebase
$ git rebase origin/main
Auto-merging src/auth/login.ts
CONFLICT (content): Merge conflict in src/auth/login.ts

# 第 2 步：檢查衝突
$ git status
both modified:   src/auth/login.ts

# 第 3 步：解決衝突
$ vim src/auth/login.ts

# 在編輯器中手動解決衝突
<<<<<<< HEAD
function login(email: string, password: string) {
  return authenticateUser(email, password);
}
=======
function login(email: string, password: string) {
  const user = await findUserByEmail(email);
  if (!user) throw new Error('User not found');
  return bcrypt.compare(password, user.password_hash);
}
>>>>>>> feature/user-auth

# 解決後（保留 feature 分支的實作，但整合 main 的改進）
function login(email: string, password: string) {
  const user = await findUserByEmail(email);
  if (!user) throw new Error('User not found');
  return bcrypt.compare(password, user.password_hash);
}

# 第 4 步：標記衝突已解決
$ git add src/auth/login.ts

# 第 5 步：繼續 rebase
$ git rebase --continue

# 第 6 步：驗證結果
$ npm test
✓ All tests passed

# 第 7 步：強制推送（因為 rebase 改寫了歷史）
$ git push origin feature/user-auth --force-with-lease

範例 3：在完成前發現問題

情境：在收尾時發現設計問題

處理決策：

## 發現的問題

在完成收尾時，我發現當前的 session 設計有潛在的安全問題。

**問題描述**：
目前的 JWT token 沒有過期時間，可能會被濫用。

**可能的解決方案**：

**方案 1：在這個 PR 中修正**
- 優點：問題立即解決
- 缺點：會延遲合併，影響其他依賴此功能的功能

**方案 2：建立 follow-up PR**
- 優點：當前功能可以及時合併
- 缺點：需要追蹤並確保 follow-up 完成

**方案 3：回退實作，重新設計**
- 優點：確保設計正確
- 缺點：會花費更多時間

**我的建議**：方案 2
1. 在當前 PR 中加上 TODO 註解和警告
2. 建立高優先的 follow-up issue
3. 在下次 sprint 優先處理

**行動計畫**：
- [x] 在當前 PR 中加上安全性警告註解
- [x] 建立 issue #456 追蹤這個問題
- [x] 安排在下個 sprint 處理
- [x] 更新风险评估文件

**審查者意見**：
請問你們認為這個處理方式是否妥當？
或者你們有更好的建議？

完成分支的檢查清單

程式碼品質

- [ ] 所有 linting 檢查通過
- [ ] TypeScript 型別檢查無誤
- [ ] 程式碼已格式化
- [ ] 沒有除錯程式碼
- [ ] 沒有註解掉的程式碼
- [ ] 沒有無用的 import 和變數
- [ ] 複雜邏輯有適當註解

測試完整性

- [ ] 所有測試通過（100% pass rate）
- [ ] 測試覆蓋率符合標準
- [ ] 關鍵功能有測試保護
- [ ] 邊界條件有測試
- [ ] 錯誤情況有測試
- [ ] 整合測試通過

功能驗證

- [ ] 所有承諾的功能已實作
- [ ] 功能符合需求描述
- [ ] 使用者體驗符合預期
- [ ] 錯誤處理完整且合理
- [ ] 與現有功能相容
- [ ] 效能符合預期

文件更新

- [ ] README 已更新（如需要）
- [ ] API 文件已更新（如需要）
- [ ] CHANGELOG 已更新
- [ ] Migration guide 已建立（如有 breaking changes）
- [ ] 重要決策有記錄

Git 清理

- [ ] 分支歷史乾淨（無 merge commits）
- [ ] Commit 訊息清楚且符合規範
- [ ] 與主分支同步（rebase 到最新）
- [ ] 推送到遠端
- [ ] PR 描述完整清楚

常見問題

Q1：分支還沒完成但需要發布怎麼辦？

A：考慮以下選項：

功能開關：完成部分功能，用開關控制
拆分 PR：將完成的部分先合併
延後發布：等待功能完成再發布

Q2：發現嚴重問題怎麼辦？

A：

立即修復：如果問題嚴重且容易修復
回退變更：如果問題難以快速修復
追蹤問題：建立高優先 issue 追蹤

Q3：測試失敗怎麼辦？

A：

修復測試：如果測試合理
更新測試：如果測試過時或錯誤
補充測試：如果測試覆蓋不足

Q4：需要 rebase 還是 merge？

A：

Rebase：保持乾淨的線性歷史（推薦）
Merge：保留完整的開發歷史（適合大型 feature）