pr-review-release

name	pr-review-release
description	PR Code Review 評估與完整發布流程。當使用者提到 code review、PR 審查、review 建議處理、merge PR、發布版本、release、squash merge、版本標籤時自動啟用。包含評估 Copilot/人工 review 建議、程式碼修正、Git 合併、語意化版本更新、CHANGELOG、打包發布的完整工作流程。PR review evaluation and release workflow for processing code review comments, merging PRs, semantic versioning, and publishing releases.
metadata	{"author":"singular-blockly","version":"1.6.0","category":"release"}
license	Apache-2.0

PR Code Review 評估與發布流程 PR Review & Release Workflow

以專案開發者角度評估 PR Code Review，並執行完整發布流程。 Evaluate PR code reviews from a project developer's perspective and execute the complete release workflow.

適用情境 When to Use

• 需要處理 PR 上的 code review 建議
• 評估 Copilot review 或人工審查意見
• 合併 PR 後需要發布新版本
• 執行完整的發布流程（版本號、CHANGELOG、標籤、Release）
• 需要 squash merge 並清理已合併的分支
• 定期清理已合併到 master 的舊本地分支

工作流程 Workflow

Phase 0: 等待 Copilot Review（必須）Wait for Copilot Review (REQUIRED)

⚠️ 阻塞型步驟：此步驟必須完成才能進入 Code Review 評估階段。

💡 Copilot Code Review 已在 GitHub 倉庫設定中配置為自動觸發，無需手動請求。

方法 A：直接使用 gh CLI（推薦）

直接使用 gh CLI 查詢最可靠，避免 PowerShell 跳脫問題。

1. 查詢 Review 狀態

   # 查詢 PR 的所有 reviews（JSON 陣列）
   gh pr view {PR_NUMBER} --json reviews --jq ".reviews"
   
   # 過濾 Copilot review（看 author.login）
   # Copilot reviewer login: "copilot-pull-request-reviewer" 或 "Copilot"
   

   回傳的 JSON 中找 author.login 為 copilot-pull-request-reviewer 的項目， 取最後一筆的 state 欄位。完成狀態為 COMMENTED、APPROVED 或 CHANGES_REQUESTED。

2. 取得 Line Comments（逐行建議）

   # 先取得 repo 全名
   $repo = gh repo view --json nameWithOwner --jq ".nameWithOwner"
   
   # 取得 Copilot 的 line comments
   gh api "repos/$repo/pulls/{PR_NUMBER}/comments" --jq '.[] | select(.user.login == "copilot-pull-request-reviewer" or .user.login == "Copilot") | {path, line, body}'
   

3. Agent 整合用法（必須執行）

   // 步驟 1: 查詢 PR review 狀態
   run_in_terminal({
     command: 'gh pr view {PR_NUMBER} --json reviews --jq ".reviews"',
     isBackground: false,
     goal: '查詢 Copilot Review 狀態',
   });
   // 步驟 2: 解析 JSON 輸出，檢查是否有 copilot-pull-request-reviewer
   // 步驟 3: 若尚未出現，等待 60 秒後重試（最多 30 分鐘）
   // 步驟 4: Review 完成後，取得 line comments
   run_in_terminal({
     command: '$repo = gh repo view --json nameWithOwner --jq ".nameWithOwner"; gh api "repos/$repo/pulls/{PR_NUMBER}/comments" --jq \'[.[] | select(.user.login == "copilot-pull-request-reviewer" or .user.login == "Copilot") | {path, line, body, id}]\'',
     isBackground: false,
     goal: '取得 Copilot line comments',
   });
   

4. 若 Copilot Review 未自動觸發

   使用 MCP 工具手動請求：

   mcp_github_request_copilot_review({
     owner: "{OWNER}",
     repo: "{REPO}",
     pullNumber: {PR_NUMBER}
   });
   

方法 B：使用輪詢腳本（背景執行）

若偏好背景輪詢，可使用已修復的腳本（v2.0.0）：

# 背景模式執行
.\.github\skills\pr-review-release\scripts\poll-review.ps1

# 自訂參數
.\.github\skills\pr-review-release\scripts\poll-review.ps1 -PrNumber 123 -TimeoutMinutes 60 -PollIntervalSeconds 30

腳本行為：

• 每 60 秒查詢一次 Copilot review 狀態
• 使用 PowerShell 原生 Where-Object 過濾（避免 jq 跳脫問題）
• 動態取得 owner/repo（避免文字佔位符問題）
• COMMENTED / APPROVED：exit 0 | CHANGES_REQUESTED：exit 1 | 逾時：exit 2

---

Phase 1: Code Review 評估 Review Evaluation

1. 讀取 PR Review 評論

   # 取得目前分支的 PR 資訊
   gh pr view --json reviews,comments,number
   
   # 取得詳細的 review 評論
   gh pr view --json reviews --jq '.reviews[] | {author: .author.login, state: .state, body: .body}'
   

2. 評估每條建議，以專業開發者角度判斷：

   判斷結果	標準	範例
   ✅ 採納	真正有價值、能改善程式碼品質	修復潛在 bug、改善效能、增強可讀性
   ❌ 忽略	基於錯誤理解或不符合專案架構	過度工程化、不了解上下文、風格偏好

3. 記錄評估結果，清楚說明每條建議的採納/忽略理由

Phase 2: 程式碼修正 Code Fixes

若有採納的建議：

1. 修正程式碼

   • 根據採納的建議進行修改
   • 確保符合專案規範（參考 copilot-instructions.md）

2. 驗證修正

   # 執行測試
   npm test
   
   # 執行 lint
   npm run lint
   

Phase 3: 程式碼簡化（必須）Code Simplification (REQUIRED)

⚠️ 阻塞型步驟：此步驟必須完成才能進入 Git 操作階段。

修正 Code Review 建議後，必須使用 code-simplifier 技能進行程式碼簡化：

1. 執行程式碼簡化檢查

   # 取得本次變更的檔案
   git diff --name-only origin/master | grep -E '\.(ts|js)$'
   

2. 強制簡化流程

   • 閱讀 code-simplifier 技能文件
   • 對所有變更的 TypeScript/JavaScript 檔案執行簡化
   • 確保遵循專案的 coding standards

3. 簡化完成標準

   • 減少不必要的巢狀結構
   • 移除冗餘程式碼和抽象
   • 變數和函式命名清晰
   • 無描述顯而易見程式碼的註解
   • 測試通過且功能不變

4. 提交簡化變更

   git add .
   git commit -m "refactor: simplify code before release"
   

💡 Agent 整合：輸入「簡化程式碼」、「refactor」或 @code-simplifier 觸發技能。

❌ 禁止跳過：未完成程式碼簡化不得進入 Phase 4。

Phase 4: Git 操作 Git Operations

1. 提交變更（若有修正）

   git add .
   git commit -m "fix: address code review feedback"
   

2. 推送並合併

   # 推送到功能分支
   git push origin HEAD
   
   # Squash merge PR（--delete-branch 會自動刪除遠端分支）
   gh pr merge --squash --delete-branch
   

   Agent 使用 MCP 工具合併時：mcp_github_merge_pull_request 不會自動刪除遠端分支，必須在步驟 4 手動刪除。

3. 同步主分支

   git checkout master
   git pull origin master
   git status -sb
   

   確認主分支已同步且工作目錄乾淨，再進入發布流程。

4. 清理已合併分支 Branch Cleanup

   # 刪除遠端功能分支（若未被 --delete-branch 自動刪除）
   git push origin --delete feature-branch-name
   
   # 更新遠端分支資訊，移除已刪除的遠端分支
   git fetch --prune
   
   # 刪除本地功能分支（若尚未刪除）
   git branch -d feature-branch-name
   
   # 批次刪除所有已合併到 master 的本地分支
   git branch --merged master | grep -v "master" | xargs -r git branch -d
   
   # 列出並清理標記為 [gone] 的分支（遠端已刪除）
   git branch -vv | grep ': gone]' | awk '{print $1}' | xargs -r git branch -d
   

5. 清理 Worktrees（如有使用）

   # 列出所有 worktrees
   git worktree list
   
   # 移除關聯已刪除分支的 worktree
   git worktree remove path/to/worktree
   

Phase 5: 發布流程 Release Process

按照專案憲法（constitution.md）或發布規範執行：

5.1 版本管理 Version Management

1. 決定版本號（遵循語意化版本）

   • patch: Bug 修復、小改進 (0.0.X)
   • minor: 新功能、向後相容 (0.X.0)
   • major: 破壞性變更 (X.0.0)

2. 更新版本號（避免自動建立輕量 tag）

   npm version patch --no-git-tag-version  # 或 minor / major
   

3. 更新 CHANGELOG.md

   • 新增雙語條目（中英文）
   • 格式遵循 Keep a Changelog

4. 提交版本更新

   git add package.json package-lock.json CHANGELOG.md
   git commit -m "chore(release): 發布版本 {VERSION}"
   

5.2 品質驗證 Quality Verification

# 完整測試
npm test

# Lint 檢查
npm run lint

# 建置驗證
npm run compile

5.3 建置與打包 Build & Package

# 生產建置
npm run package

# 打包 VSIX（若為 VS Code 擴充功能）
npx @vscode/vsce package

5.4 Git 標籤 Git Tagging

⚠️ 重要：所有版本標籤必須使用 Annotated Tags（-a 參數）

Annotated tags 包含建立者、日期、訊息等元資料，是正式發布的標準做法。

# 建立 Annotated Tag（必須使用 -a 參數）
git tag -a v{VERSION} -m "Release v{VERSION}"

# 推送標籤到遠端
git push origin v{VERSION}

# 驗證標籤類型（應顯示 tag 而非 commit）
git cat-file -t v{VERSION}

❌ 禁止使用 Lightweight Tags：

# 錯誤示範 - 不要這樣做！
git tag v{VERSION}  # 缺少 -a 參數，會建立 lightweight tag

5.5 GitHub Release（必要步驟 REQUIRED）

⚠️ 重要：此步驟不可省略！Git tag 不等於 GitHub Release。

注意：Release 公告容易因 CLI 字串轉義導致跑版，建議使用臨時檔（release-notes.md）輸入。

@'
## ✨ New Features | 新功能

### Feature Name | 功能名稱
- English description | 中文說明

## 🐛 Bug Fixes | 修復
- Fixed issue | 修正問題

## 📦 Download | 下載
- **VSIX**: singular-blockly-{VERSION}.vsix

---
**Full Changelog | 完整變更日誌**: https://github.com/{owner}/{repo}/blob/master/CHANGELOG.md
'@ | Set-Content -Path "release-notes.md" -Encoding UTF8

gh release create v{VERSION} -t "v{VERSION}" -F release-notes.md ./singular-blockly-{VERSION}.vsix

Remove-Item -Force release-notes.md

Release 版面檢核與修正：

gh release view v{VERSION} --json body
gh release view v{VERSION} --web

若格式跑掉，修正 release-notes.md 後重新更新：

gh release edit v{VERSION} -F release-notes.md

5.6 清理 Cleanup

# 移除 VSIX 安裝包（必須執行！）
Remove-Item -Force singular-blockly-{VERSION}.vsix

# 移除暫時發布說明檔（若未在 5.5 步驟中移除）
Remove-Item -Force release-notes.md -ErrorAction SilentlyContinue

# 驗證發布連結可存取
gh release view v{VERSION} --web

⚠️ 必須移除 VSIX：VSIX 是建置產物，不應留在工作目錄中。GitHub Release 已附加此檔案，本地保留無意義且會造成混亂。

檢查清單 Checklist

等待 Review 階段（阻塞型）

• 使用 gh pr view 查詢 Copilot Review 狀態（或使用輪詢腳本）
• Review 狀態已確認（COMMENTED / APPROVED / CHANGES_REQUESTED）
• 已取得 line comments（gh api repos/{owner}/{repo}/pulls/{n}/comments）

❌ 禁止跳過：未取得 Copilot Review 結果不得進入 Phase 1。

Code Review 階段

• 讀取所有 PR review 評論
• 評估每條建議並記錄理由
• 完成採納建議的程式碼修正
• 測試通過

程式碼簡化階段（阻塞型）

• 已識別所有變更的 TS/JS 檔案
• 已執行 code-simplifier 技能
• 無不必要的巢狀結構
• 無冗餘程式碼和抽象
• 變數和函式命名清晰
• 無描述顯而易見程式碼的註解
• 測試通過且功能不變
• 簡化變更已提交

Git 操作階段

• 變更已提交並推送
• PR 已 squash merge
• 主分支已同步
• 遠端功能分支已刪除（git push origin --delete 或 --delete-branch）
• 本地功能分支已刪除（git branch -d）
• 已清理其他舊的已合併分支

發布階段

• 版本號已更新
• CHANGELOG.md 已更新（雙語）
• 所有測試通過
• 成功建置打包 VSIX
• Git Annotated Tag 已建立並推送（使用 git tag -a）
• GitHub Release 已建立（使用 gh release create）
• Release 含雙語說明與 VSIX 附件
• Release 版面檢核完成（必要時已修正）
• 發布連結可存取（使用 gh release view 驗證）
• 本地 VSIX 已移除（Remove-Item singular-blockly-{VERSION}.vsix）
• release-notes.md 已移除（若有使用）

輸出格式 Output Format

完成後提供執行摘要：

## 執行摘要 Execution Summary

| 項目             | 狀態                            |
| ---------------- | ------------------------------- |
| Code Review 評估 | ✅ 完成（採納 X 條，忽略 Y 條） |
| 程式碼修正       | ✅/⏭️ 完成/無需修正             |
| PR 合併          | ✅ Squash merged                |
| 版本更新         | ✅ vX.Y.Z                       |
| 發布             | ✅ 完成                         |

### 變更檔案 Changed Files

- `package.json`
- `CHANGELOG.md`
- ...

### 發布連結 Release Link

https://github.com/{owner}/{repo}/releases/tag/v{VERSION}

相關資源 Related Resources

• 語意化版本規範
• Keep a Changelog
• git-workflow 技能 - 從 commit 到 PR 建立（自動觸發本技能）
• code-simplifier 技能 - 程式碼簡化與重構（阻塞型）