# 发布评审：为候选版本整理发布评审记录，按发布准入条件评审，并由负责人批准或暂缓发布

Roles:

- Releaser
- Reviewer

负责人给出一个候选版本：版本号，以及当前分支上的一个 commit。
发布评审记录是 `docs/releases/版本号/release-review.md` 这一个文件，由 Releaser 写入并提交到当前分支。
本规程只改动该版本的 `docs/releases/版本号/` 目录，不改动任何其他文件，也不改写已有提交。
评审最多两轮：第一轮评审 Releaser 的首次提交；有发现时，Releaser 修正并再次提交，第二轮评审这次修正提交；第二轮后不再修正、不再评审。
Captain 以仓库记录确认每次新提交的身份，而不以任何角色的自述为准。

### RELEASE-REVIEW-1

Releaser 向负责人提问并等待回答时，负责人的回答续接本条行为。

当负责人给出候选版本时，Captain shall prompt Releaser:

> 为下方请求中的候选版本整理发布评审材料，写成一份发布评审记录，并一次提交到当前分支。
> 先从请求中确定版本号与候选 commit，并确认该 commit 位于当前分支上（即当前 HEAD 或其祖先）。
> 若请求未给出版本号或候选 commit，或该 commit 不在当前分支上，向负责人提一个问题，不改动任何文件、不提交，等待回答。
>
> 把记录写在 docs/releases/版本号/release-review.md，其中版本号取自请求，记录包括：
> 一、测试结果：从 docs/verification/ 的测试报告摘录候选 commit 对应的测试通过率，写成数字（通过数/总数与百分比），并注明出处报告的路径；
> 二、未覆盖的规约条目：从测试报告与追溯矩阵中逐条列出未被测试覆盖的规约条目编号，每条写明未覆盖的理由；
> 三、变更清单：列出候选 commit 可达的上一个标签（不含）到候选 commit（含）之间的全部提交；若没有标签，则自首个提交起；写明所用的起止点；
> 四、已知问题：逐条列出，每条写明处置（修复计划、规避措施或接受风险及其理由）；
> 五、回退方案：按顺序写出可执行的步骤，每一步给出具体命令或操作、执行前提、预期结果与验证方法。
>
> 只写仓库中可以核实的事实，不编造数字、条目或问题；某项资料在仓库中缺失时，如实写明缺失之处。
> 只改动 docs/releases/版本号/ 目录，不改动固件代码、测试报告或其他文件。
> 完成后做一次新提交，仓库有 @specs/packages/git.md 时遵循之；提交信息简要说明本次整理的版本与内容；不要修改已有提交。
> 回复中写明版本号、候选 commit、评审记录路径与新提交。
>
> > 原始请求：<caller-input>

Results:
- `drafted`: Releaser 写好发布评审记录并做了一次新提交。Output shall include `releaserOutput: <verbatim final text>` and `latestCommit: <commit identity>`.

### RELEASE-REVIEW-2

当 Releaser 提交发布评审记录后，进入第一轮评审，Captain shall prompt Reviewer:

> 第一轮发布评审开始。
> 阅读下方提交中的发布评审记录及其提交信息，并对照仓库核实记录内容。
>
> > 原始请求：<caller-input>
> > 记录提交：<latest-commit>
> > Releaser 说明：<releaser-output>
>
> 按以下发布准入条件评审：
> 一、测试通过率必须是数字，且与 docs/verification/ 中所注出处报告一致；
> 二、每条未覆盖的规约条目必须有理由，且未覆盖条目没有遗漏；
> 三、回退方案的每一步必须可执行：命令或操作具体、前提明确、顺序正确、可以验证结果；
> 四、每个已知问题必须有处置。
>
> 发现按编号列出，每条写明违反的准入条件、所在位置与应如何修正。
> 只提出影响发布准入的问题，不提出措辞或格式偏好。
> 没有发现时，明确写出“评审完成，没有发现”。
> 不要修改文件或提交，只报告发现。

Results:
- `hasFindings`: Reviewer 列出了一条或多条发现；进度报告、状态更新或稍后给出结果的承诺不支持任何评审结果。Output shall include `reviewerOutput: <verbatim final text>`.
- `noFindings`: Reviewer 明确报告评审完成且没有发现；进度报告、状态更新或稍后给出结果的承诺不支持任何评审结果。

### RELEASE-REVIEW-3

当第一轮评审有发现时，Captain shall prompt Releaser:

> 评审委员对发布评审记录提出了下方的发现。
> 逐条修正：每条发现都在记录中改正；若某条发现所指的事实确实如此，在记录中补充说明或依据，使记录满足发布准入条件。
> 修正前对照仓库核实，只写可以核实的事实，不编造数字、条目或问题。
> 只改动 docs/releases/版本号/ 目录，不改动固件代码、测试报告或其他文件。
> 完成后做一次新提交，仓库有 @specs/packages/git.md 时遵循之；提交信息按编号简要说明每条发现的修正；不要修改已有提交。
> 回复中逐条写明每条发现的处置，并写明评审记录路径与新提交。
>
> > 原始请求：<caller-input>
> > 评审发现：<reviewer-output>

Results:
- `revised`: Releaser 修正了发布评审记录并做了一次新提交。Output shall include `releaserOutput: <verbatim final text>` and `latestCommit: <commit identity>`.

### RELEASE-REVIEW-4

当 Releaser 提交修正后，进入第二轮评审，也是最后一轮，Captain shall prompt Reviewer:

> 第二轮发布评审开始，这是最后一轮。
> 阅读下方修正提交及其提交信息，核实上一轮的每条发现是否已修正，并对照仓库重新核实整份发布评审记录。
> 沿用上一轮的发现编号；已修正的发现不再提出。
>
> > 原始请求：<caller-input>
> > 修正提交：<latest-commit>
> > Releaser 说明：<releaser-output>
>
> 按以下发布准入条件评审：
> 一、测试通过率必须是数字，且与 docs/verification/ 中所注出处报告一致；
> 二、每条未覆盖的规约条目必须有理由，且未覆盖条目没有遗漏；
> 三、回退方案的每一步必须可执行：命令或操作具体、前提明确、顺序正确、可以验证结果；
> 四、每个已知问题必须有处置。
>
> 发现按编号列出，每条写明违反的准入条件、所在位置与应如何修正。
> 只提出影响发布准入的问题，不提出措辞或格式偏好。
> 没有发现时，明确写出“评审完成，没有发现”。
> 不要修改文件或提交，只报告发现。

Results:
- `hasFindings`: Reviewer 列出了一条或多条仍未解决的发现；进度报告、状态更新或稍后给出结果的承诺不支持任何评审结果。此时规程结束，报告为评审未通过，返回 Reviewer 的发现与最后一次记录提交，不向负责人提出批准问题。Output shall include `reviewerOutput: <verbatim final text>`.
- `noFindings`: Reviewer 明确报告评审完成且没有发现；进度报告、状态更新或稍后给出结果的承诺不支持任何评审结果。

### RELEASE-REVIEW-5

当任一轮评审没有发现时，Captain shall 请负责人作出发布决定:

> 发布评审已通过。
> 向负责人提出且只提出一个问题：“是否批准发布”后接下方请求中的版本号与问号，然后等待回答。
> 负责人同意时，报告该版本为已批准发布，写明版本号、评审记录路径与下方的记录提交。
> 负责人不同意时，报告该版本为暂缓发布，写明版本号、评审记录路径与记录提交，并原样记录负责人给出的理由；负责人未给出理由时，写明未给出理由。
>
> > 原始请求：<caller-input>
> > 记录提交：<latest-commit>
> > Releaser 说明：<releaser-output>

Results:
- `approved`: 负责人同意发布；规程结束，返回的报告标明已批准发布，并写明版本号、评审记录路径与记录提交。Output shall include `releaseReport: <verbatim final text>`.
- `deferred`: 负责人不同意发布；规程结束，返回的报告标明暂缓发布，写明版本号、评审记录路径与记录提交，并原样记录负责人的理由。Output shall include `releaseReport: <verbatim final text>`.