release-review

比较两个 Git 标签或提交，并生成两份部署就绪报告：面向人工测试人员的 QA 报告（用户可见的流程，不包含代码细节），以及 Developer 报告（技术细节、文件路径，以及相关代码片段）。两份报告都要指出部署前必须验证的内容，并标记可能被忽略的问题。

用法：

• /release-review v1.2.0 v1.3.0 - 分析两个标签之间的变更
• /release-review abc1234 def5678 - 分析两个提交之间的变更
• /release-review v1.2.0 HEAD - 分析从某个标签到当前 HEAD 的变更

说明：

1. 解析位置参数：

   • $1 = 起始点（不包含），通常是上次部署的版本。可以是 Git 标签、提交 SHA、分支名称或 HEAD
   • $2 = 终点（包含），通常是即将部署的版本。可以是 Git 标签、提交 SHA、分支名称或 HEAD
   • 如果缺少 $1 或 $2，显示以下消息并停止：

     ## 缺少参数
     
     用法：/release-review <base-ref> <target-ref>
     
     示例：
       /release-review v1.2.0 v1.3.0
       /release-review abc1234 def5678
       /release-review v1.2.0 HEAD
     

2. 验证引用：

   • 运行 git rev-parse --verify <base-ref> 和 git rev-parse --verify <target-ref>，确认两个引用都存在
   • 如果任一引用无效，显示错误并停止：

     无效的 Git 引用："<ref>"
     请确保该标签、提交或分支在本地存在。你可能需要先运行 `git fetch --tags`。
     

3. 收集所有变更：

   运行以下 Git 命令，全面了解两个引用之间的变更：

   a) 提交日志：

   • 运行 git log --oneline --no-merges <base-ref>..<target-ref>，列出所有非合并提交
   • 运行 git log --oneline --merges <base-ref>..<target-ref>，单独列出合并提交（这些提交表示 PR 合并和功能边界）

   b) 文件级摘要：

   • 运行 git diff --stat <base-ref>..<target-ref>，获取整体变更统计
   • 运行 git diff --name-status <base-ref>..<target-ref>，将文件分类为新增（A）、修改（M）、删除（D）或重命名（R）

   c) 完整差异以供分析：

   • 运行 git diff <base-ref>..<target-ref>，获取完整差异
   • 如果差异非常庞大，优先阅读影响最大的文件（新文件、大幅修改的文件、配置变更、迁移文件），并快速浏览其余内容

4. 盘点变更：

   将所有变更按应用的功能区域分组，整理成结构化清单：

   ## Change Inventory: <base-ref> → <target-ref>
   
   **Commits:** <N> (non-merge) + <N> (merges)
   **Files changed:** <N> added, <N> modified, <N> deleted, <N> renamed
   
   ### By Area
   
   #### <Area 1> (e.g., Authentication, API, UI/Components, Database, etc.)
   - `path/to/file.ts` — <brief description of change>
   - `path/to/other.ts` — <brief description of change>
   
   #### <Area 2>
   - ...
   
   ### Notable Changes
   - <Highlight any particularly significant or risky changes>
   - <New dependencies added or removed>
   - <Database migrations>
   - <Configuration changes (env vars, feature flags, etc.)>
   - <API contract changes (new endpoints, modified request/response shapes, breaking changes)>
   

   分组指南：

   • 按应用的功能区域分组，而不是按目录分组
   • 指出影响多个区域的跨领域变更
   • 单独列出基础设施变更（CI/CD、构建配置、部署脚本）
   • 标记共享工具、类型或核心模块的任何变更，这些变更可能产生连锁影响

5. 分析部署风险和测试要求：

   对每个变更区域评估风险，并指出部署前必须验证的内容：

   ## Deployment Readiness Analysis
   
   ### Critical — Must verify before deploying
   These changes carry the highest risk and must be manually or automatically verified.
   
   **#1** — <Area/feature>
   - **What changed:** <concise description>
   - **Risk:** <why this is critical — data loss, auth bypass, breaking API, etc.>
   - **Verify:** <specific things to test — exact user flows, API calls, edge cases>
   
   **#2** — ...
   
   ### Important — Should verify
   These changes are significant but lower risk.
   
   **#3** — <Area/feature>
   - **What changed:** <concise description>
   - **Risk:** <potential impact>
   - **Verify:** <what to check>
   
   ### Low Risk — Spot check
   These changes are unlikely to cause issues but deserve a quick look.
   
   **#4** — <Area/feature>
   - **What changed:** <concise description>
   - **Verify:** <quick check>
   
   ### No Action Needed
   - <List of changes that don't require verification: docs, comments, formatting, test-only changes, etc.>
   

   风险评估标准：

   • 严重： 身份验证/安全变更、支付/计费、数据迁移、破坏性 API 变更、核心业务逻辑、共享基础设施
   • 重要： 面向用户的新功能、现有流程修改、依赖项更新、配置变更
   • 低风险： UI 微调、文案变更、日志改进、非关键错误修复
   • 无需操作： 文档、仅测试变更、代码注释、格式调整

6. 检查端到端测试覆盖情况：

   确认第 5 步中识别的区域是否已由现有端到端测试覆盖。 a) 确认端到端测试配置：

   • 查找 Playwright 配置（playwright.config.ts、playwright.config.js）、Cypress 配置（cypress.config.ts、cypress.json）或其他端到端测试框架
   • 确定端到端测试目录结构和文件命名模式
   • 如果没有找到端到端测试框架，请注明这一点，并跳到步骤 7

   b) 将更改映射到端到端测试覆盖范围：

   • 对于步骤 5 中每个 Critical 和 Important 项，在现有端到端测试文件中搜索验证受影响功能的测试
   • 查找与更改区域相符的测试描述、路由导航、选择器交互和 API 调用
   • 阅读相关端到端测试文件，确认它们确实覆盖了需要验证的场景

   c) 报告覆盖范围：

   ## E2E Test Coverage
   
   ### Covered
   - **#1** (<Area>) — Covered by `e2e/tests/auth.spec.ts` (tests: "should login with valid credentials", "should reject expired tokens")
   - **#3** (<Area>) — Covered by `e2e/tests/settings.spec.ts` (tests: "should update profile name")
   
   ### Partially Covered
   - **#2** (<Area>) — `e2e/tests/checkout.spec.ts` covers the happy path but does NOT test the new discount logic added in this release
   
   ### Not Covered
   - **#5** (<Area>) — No e2e tests found for this flow
   - **#6** (<Area>) — E2e tests exist but are outdated (test references removed component)
   
   ### Coverage Summary
   - Critical items covered: <N>/<total>
   - Important items covered: <N>/<total>
   - Recommendation: <brief recommendation on whether e2e coverage is sufficient for a safe deployment>
   

7. 指出可能遗漏的问题：

   查找仅凭更改清单可能不易发现的模式和风险：

   ## Potential Overlooked Issues
   
   ### Dependency & Compatibility
   - <New/updated dependencies that might introduce breaking changes or vulnerabilities>
   - <Peer dependency conflicts>
   - <Node/runtime version requirements that changed>
   
   ### Data & State
   - <Database migrations that need to be run — and in what order>
   - <Cache invalidation needed after deployment>
   - <State schema changes that could break existing user sessions or stored data>
   - <Background jobs or queues that need to be drained or restarted>
   
   ### Configuration & Environment
   - <New environment variables that must be set before deployment>
   - <Feature flags that need to be toggled>
   - <Third-party service configuration changes>
   
   ### Cross-cutting Concerns
   - <Changes to shared utilities/types that affect code outside the diff>
   - <API contract changes that may break mobile or external consumers>
   - <Timing or race condition risks from concurrent changes>
   - <Rollback considerations — can this release be safely rolled back?>
   
   ### Subtle Risks
   - <Removed error handling or fallback behavior>
   - <Changed default values that could affect existing users>
   - <Renamed or removed public API methods that external code may depend on>
   - <Performance implications of the changes (new queries, larger payloads, etc.)>
   

   只包含相关的部分，不要用推测性问题凑篇幅。每个条目都应以 diff 中观察到的内容为依据。

8. 呈现最终报告：

   输出两份清晰分开的报告。先提供共用变更日志，然后提供 QA 报告，最后提供开发者报告。

   ---

   8a. 共用变更日志

   以易于阅读的方式总结所有更改，适用于发布说明。使用通俗语言，不写文件路径或代码。按功能领域归类，并将每项写成面向用户的项目符号。

   ## Changelog: <base-ref> → <target-ref>
   
   ### New Features
   - <Feature or improvement visible to users — written in plain English>
   - ...
   
   ### Bug Fixes
   - <Bug that was fixed, described in user-facing terms>
   - ...
   
   ### Internal & Infrastructure
   - <Non-user-facing changes: config, tooling, dependencies, refactors — keep brief>
   - ...
   

   只包含有条目的部分。省略空白部分。

   ---

   8b. QA 报告——手动测试

   面向执行手动 QA 的测试人员。不写文件路径、代码片段或技术内部细节。只关注测试人员需要了解和验证的内容。

   ## QA Report: <base-ref> → <target-ref>
   
   ### What Changed (QA Summary)
   Describe each changed area in user-facing terms: what the feature does, who it affects, and how users interact with it.
   
   #### <Area 1> — <Risk level: Critical / Important / Low>
   <1–3 sentence plain-English description of what changed from a user's perspective>
   
   #### <Area 2> — <Risk level>
   ...
   
   ### Test Scenarios
   
   #### Critical — Must verify before deploying
   **<Area/Feature>**
   - [ ] <User-facing test step — e.g., "Log in with a valid account and confirm the dashboard loads">
   - [ ] <Another step>
   
   #### Important — Should verify
   **<Area/Feature>**
   - [ ] <Test step>
   
   #### Low Risk — Spot check
   **<Area/Feature>**
   - [ ] <Quick check>
   
   ### Pre-deployment Checklist (QA)
   - [ ] <QA action — e.g., "Smoke test the login flow on staging">
   - [ ] <QA action — e.g., "Verify checkout works end-to-end with a test card">
   
   ### Verdict
   **Deployment risk level:** Critical / High / Medium / Low
   **E2E coverage:** Sufficient / Needs attention / Insufficient
   **Recommendation:** <one-sentence summary — e.g., "Safe to deploy after verifying items #1 and #2">
   

   ---

   8c. 开发者报告——技术细节

   面向开发者和 DevOps。包含文件路径、技术背景，以及有助于说明风险或操作的代码片段。本报告涵盖步骤 4–7 的所有内容。

   ## Developer Report: <base-ref> → <target-ref>
   
   <Change Inventory from step 4>
   
   <Deployment Readiness Analysis from step 5>
   
   <E2E Test Coverage from step 6>
   
   <Potential Overlooked Issues from step 7>
   
   ### Pre-deployment Checklist (Technical)
   - [ ] <Technical action — e.g., "Run migration `20240101_add_user_roles.sql`">
   - [ ] <Technical action — e.g., "Set `FEATURE_FLAG_X=true` in production env">
   - [ ] <Technical action — e.g., "Notify mobile team of breaking change to `/api/v2/users` response shape">
   
   ### Verdict
   **Deployment risk level:** Critical / High / Medium / Low
   **E2E coverage:** Sufficient / Needs attention / Insufficient
   **Recommendation:** <one-sentence summary>
   

9. 处理边缘情况：

   • 如果两个引用之间没有更改，请显示“<base-ref> 和 <target-ref> 之间未找到更改。”并停止
   • 如果 diff 非常大（数百个文件），请重点关注影响最大的更改，并说明无法在一次审查中完成全面审查
   • 如果未检测到端到端测试框架，请在覆盖范围部分注明，并建议设置一个框架
   • 如果 base ref 位于 target ref 之后（顺序相反），请提醒开发者，并询问他们是否想交换参数