qa-checklist

根据差异编写手动 QA 检查清单

编写一份简短的检查清单，让人工可以在已部署的应用中逐项点击，确认此更改有效。读者是拥有浏览器和测试账号的人，而不是阅读代码的开发者。每个步骤都必须是他们可以通过 UI（或少数情况下，通过电子邮件收件箱／API 客户端，如果更改只会在那里体现）执行并观察结果的操作。

这不是回归测试套件，也不是代码审查。只涵盖此差异更改的内容，以及一两个最可能受到连带影响的相邻流程。如果检查清单超过约 10 个步骤，就说明范围太广了——缩减到实际受更改影响的内容。

1. 获取差异

默认将当前分支与 main 比较；如果用户指定了其他基准、提交范围或 PR，则按其指定执行。

git fetch origin
git diff origin/main...HEAD --stat     # overview
git diff origin/main...HEAD            # read the whole diff

使用 ...（merge-base），以便只查看此分支新增的内容。如果仅凭差异无法判断，则打开有改动的文件——你需要了解用户可见的行为，而不只是哪些代码行发生了变化。

2. 将代码更改转化为用户可见的行为

针对每项更改，问自己：“用户会因此看到或执行哪些不同的操作？” 这个问题决定了哪些内容应列入检查清单。

• 控制器／路由／页面——需要操作的页面和执行的操作。新增路由 → 访问该页面；更改存储／更新逻辑 → 提交表单并检查结果。
• 验证与授权——失败路径也属于 QA 步骤：提交无效输入并确认出现内联错误；尝试以无权执行操作的用户身份执行，并确认操作被阻止。
• 前端组件——需要点击的交互：开关、模态框、乐观更新、空状态、提示消息。
• 功能标志——如果行为受标志控制（例如 Pennant），则需检查两种状态：标志开启时显示功能，标志关闭时正常隐藏。如果差异说明了如何识别启用标志的账号，请注明。
• 电子邮件／通知／作业——触发操作，然后检查可观察到的结果（收到电子邮件、出现通知）。跳过没有可观察界面的内容。
• 迁移／数据更改——只有在影响用户所见内容时才检查（例如页面上的字段改名）。运行迁移属于部署检查清单，不属于此处。

完全跳过：没有行为变化的重构、仅涉及测试的更改、CI／工具链、代码风格。如果整个差异都属于这些情况，请说明——“无需手动 QA”也是有效答案。

3. 编写检查清单

输出一份 Markdown 检查清单。规则如下：

• 使用通俗英语，步骤采用祈使句——“打开一条反馈并点击 👍 表情回应”，而不是“确认 ReactionController@store 持久化了回应”。不要提及类名、代码中的路由或文件。
• 每个步骤都要包含操作和预期结果：执行 X——应看到 Y。
• 按操作流程排序，确保读者能在一次操作中从上到下完成，不必返回前面的步骤（先准备状态，再执行操作，然后检查副作用）。
• 如果存在前提条件，请在开头用一行注明：例如需要第二个测试账号、启用功能标志或已有可操作的记录。
• 控制在约 5–10 个复选框。每种行为一个步骤，而不是每条代码路径一个步骤。

格式：

## QA checklist — <one-line summary of the change>

**Before you start:** <preconditions, or omit this line>

- [ ] <action> — <expected result>
- [ ] ...

结尾不要添加其他内容——不要总结差异，也不要评论代码。