final-release-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Final Release Review

最终发布审查

Purpose

目的

Use this skill when validating the latest release candidate commit (default tip of

origin/main

) for release. It guides you to fetch remote tags, pick the previous release tag, and thoroughly inspect the

BASE_TAG...TARGET

diff for breaking changes, introduced bugs/regressions, improvement opportunities, and release risks.

The review must be stable and actionable: avoid variance between runs by using explicit gate rules, and never produce a

BLOCKED

call without concrete evidence and clear unblock actions.

当你需要验证最新的发布候选提交（默认是origin/main的最新提交）是否可发布时，使用本Skill。它会引导你拉取远程标签、选择上一个发布标签，并全面检查

BASE_TAG...TARGET

的代码差异，寻找破坏性变更、引入的Bug/回归问题、改进机会以及发布风险。

审查结果必须稳定且可执行：通过明确的准入规则避免每次执行的差异，在没有确凿证据和清晰的解除阻塞措施时，绝不能给出

BLOCKED

的结论。

Quick start

快速开始

Ensure repository root:

pwd

→

path-to-workspace/openai-agents-python

Sync tags and pick base (default

v*

bash

BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*')"

Choose target commit (default tip of

origin/main

, ensure fresh):

git fetch origin main --prune

then

TARGET="$(git rev-parse origin/main)"

Snapshot scope:

bash

git diff --stat "${BASE_TAG}"..."${TARGET}"
git diff --dirstat=files,0 "${BASE_TAG}"..."${TARGET}"
git log --oneline --reverse "${BASE_TAG}".."${TARGET}"
git diff --name-status "${BASE_TAG}"..."${TARGET}"

Deep review using
```
references/review-checklist.md
```
to spot breaking changes, regressions, and improvement chances.
Capture findings and call the release gate: ship/block with conditions; propose focused tests for risky areas.

确保处于仓库根目录：执行
```
pwd
```
，路径应为
```
path-to-workspace/openai-agents-python
```
。

同步标签并选择基准标签（默认匹配

v*

）：

bash

BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*')"

选择目标提交（默认是origin/main的最新提交，确保已同步）：先执行
```
git fetch origin main --prune
```
，再执行
```
TARGET="$(git rev-parse origin/main)"
```
。

生成差异范围快照：

bash

git diff --stat "${BASE_TAG}"..."${TARGET}"
git diff --dirstat=files,0 "${BASE_TAG}"..."${TARGET}"
git log --oneline --reverse "${BASE_TAG}".."${TARGET}"
git diff --name-status "${BASE_TAG}"..."${TARGET}"

参考
```
references/review-checklist.md
```
进行深度审查，找出破坏性变更、回归问题和改进机会。
记录审查结果并给出发布准入建议：确定是否可以发布/需要阻塞，并针对高风险区域建议针对性测试。

Deterministic gate policy

确定性准入规则

Default to 🟢 GREEN LIGHT TO SHIP unless at least one blocking trigger below is satisfied.
Use 🔴 BLOCKED only when you can cite concrete release-blocking evidence and provide actionable unblock steps.
Blocking triggers (at least one required for
```
BLOCKED
```
):
- A confirmed regression or bug introduced in
```
BASE...TARGET
```
  (for example, failing targeted test, incompatible behavior in diff, or removed behavior without fallback).
- A confirmed breaking public API/protocol/config change with missing or mismatched versioning and no migration path (for example, patch release for a breaking change).
- A concrete data-loss, corruption, or security-impacting change with unresolved mitigation.
- A release-critical packaging/build/runtime path is broken by the diff (not speculative).
Non-blocking by itself:
- Large diff size, broad refactor, or many touched files.
- "Could regress" risk statements without concrete evidence.
- Not running tests locally.
If evidence is incomplete, issue 🟢 GREEN LIGHT TO SHIP with targeted validation follow-ups instead of
```
BLOCKED
```
.

默认结论为🟢 允许发布，除非满足至少一项阻塞触发条件。
仅当你能提供确凿的发布阻塞证据，并给出清晰的解除阻塞步骤时，才能给出🔴 阻塞的结论。
阻塞触发条件（满足至少一项即可判定为阻塞）：
- ```
BASE...TARGET
```
  中存在已确认的回归问题或Bug（例如，针对性测试失败、差异中存在不兼容行为、移除了功能但未提供替代方案）。
- 存在已确认的公开API/协议/配置破坏性变更，但未进行正确的版本升级或未提供迁移路径（例如，补丁版本中包含破坏性变更）。
- 存在会导致数据丢失、损坏或安全问题的变更，且未解决相关风险。
- 差异破坏了发布关键的打包/构建/运行路径（非推测性问题）。
以下情况本身不构成阻塞：
- 差异范围大、涉及大量重构或修改了多个文件。
- 仅提出“可能存在回归”的风险声明，但无确凿证据。
- 未在本地运行测试。
若证据不完整，应给出🟢 允许发布的结论，并建议进行针对性验证，而非直接阻塞。

Workflow

工作流程

Prepare
- Run the quick-start tag command to ensure you use the latest remote tag. If the tag pattern differs, override the pattern argument (e.g.,
```
'*.*.*'
```
  ).
- If the user specifies a base tag, prefer it but still fetch remote tags first.
- Keep the working tree clean to avoid diff noise.
Assumptions
- Assume the target commit (default
```
origin/main
```
  tip) has already passed
```
$code-change-verification
```
  in CI unless the user says otherwise.
- Do not block a release solely because you did not run tests locally; focus on concrete behavioral or API risks.
- Release policy: routine releases use patch versions; use minor only for breaking changes or major feature additions. Major versions are reserved until the 1.0 release.
Map the diff
- Use
```
--stat
```
  ,
```
--dirstat
```
  , and
```
--name-status
```
  outputs to spot hot directories and file types.
- For suspicious files, prefer
```
git diff --word-diff BASE...TARGET -- <path>
```
  .
- Note any deleted or newly added tests, config, migrations, or scripts.
Analyze risk
- Walk through the categories in
```
references/review-checklist.md
```
  (breaking changes, regression clues, improvement opportunities).
- When you suspect a risk, cite the specific file/commit and explain the behavioral impact.
- For every finding, include all of:
```
Evidence
```
  ,
```
Impact
```
  , and
```
Action
```
  .
- Severity calibration:
  - 🟢 LOW: low blast radius or clearly covered behavior; no release gate impact.
  - 🟡 MODERATE: plausible user-facing regression signal; needs validation but not a confirmed blocker.
  - 🔴 HIGH: confirmed or strongly evidenced release-blocking issue.
- Suggest minimal, high-signal validation commands (targeted tests or linters) instead of generic reruns when time is tight.
- Breaking changes do not automatically require a BLOCKED release call when they are already covered by an appropriate version bump and migration/upgrade notes; only block when the bump is missing/mismatched (e.g., patch bump) or when the breaking change introduces unresolved risk.
Form a recommendation
- State BASE_TAG and TARGET explicitly.
- Provide a concise diff summary (key directories/files and counts).
- List: breaking-change candidates, probable regressions/bugs, improvement opportunities, missing release notes/migrations.
- Recommend ship/block and the exact checks needed to unblock if blocking. If a breaking change is properly versioned (minor/major), you may still recommend a GREEN LIGHT TO SHIP while calling out the change. Use emoji and boldface in the release call to make the gate obvious.
- If you cannot provide a concrete unblock checklist item, do not use
```
BLOCKED
```
  .

准备阶段
- 执行快速开始中的标签命令，确保使用最新的远程标签。若标签格式不同，可覆盖默认的匹配模式（例如
```
'*.*.*'
```
  ）。
- 若用户指定了基准标签，优先使用该标签，但仍需先拉取远程标签。
- 保持工作树干净，避免差异结果出现干扰内容。
假设前提
- 除非用户明确说明，否则默认目标提交（默认是origin/main的最新提交）已通过CI中的
```
$code-change-verification
```
  验证。
- 不要仅因未在本地运行测试就阻塞发布；重点关注具体的行为或API风险。
- 发布规则：常规发布使用补丁版本；仅当存在破坏性变更或重大功能新增时使用次版本号。主版本号需保留至1.0版本发布时使用。
分析差异范围
- 使用
```
--stat
```
  、
```
--dirstat
```
  和
```
--name-status
```
  的输出结果，找出重点修改的目录和文件类型。
- 对于可疑文件，优先使用
```
git diff --word-diff BASE...TARGET -- <path>
```
  查看详细差异。
- 记录所有被删除或新增的测试文件、配置文件、迁移脚本或脚本文件。
风险分析
- 对照
```
references/review-checklist.md
```
  中的分类（破坏性变更、回归线索、改进机会）进行检查。
- 当你怀疑存在风险时，需引用具体的文件/提交，并说明其对行为的影响。
- 每个发现都必须包含：
```
证据
```
  、
```
影响
```
  和
```
行动
```
  三部分。
- 风险等级划分：
  - 🟢 低风险：影响范围小或行为已被明确覆盖；不影响发布准入。
  - 🟡 中风险：存在可能影响用户的回归信号；需要验证但并非已确认的阻塞问题。
  - 🔴 高风险：已确认或有充分证据证明的发布阻塞问题。
- 当时间紧张时，建议使用最小化、高针对性的验证命令（例如针对性测试或检查工具），而非重新运行所有测试。
- 若破坏性变更已进行了正确的版本升级（次版本号/主版本号），并提供了迁移/升级说明，则无需阻塞发布；仅当版本升级不匹配（例如使用补丁版本）或破坏性变更存在未解决的风险时，才需要阻塞发布。
形成建议
- 明确说明BASE_TAG和TARGET的具体值。
- 提供简洁的差异摘要（关键目录/文件及修改数量）。
- 列出：潜在破坏性变更、疑似回归/Bug、改进机会、缺失的发布说明/迁移指南。
- 建议发布/阻塞，并在阻塞时给出具体的解除阻塞检查项。若破坏性变更已进行正确的版本升级（次版本号/主版本号），仍可建议🟢 允许发布，但需明确指出该变更。在发布结论中使用emoji和粗体，让准入结果清晰可见。
- 若无法提供具体的解除阻塞检查项，不要使用
```
BLOCKED
```
  结论。

Output format (required)

输出格式（必填）

All output must be in English.

Use the following report structure in every response produced by this skill. Be proactive and decisive: make a clear ship/block call near the top, and assign an explicit risk level (LOW/MODERATE/HIGH) to each finding with a short impact statement. Avoid overly cautious hedging when the risk is low and tests passed.

Always use the fixed repository URL in the Diff section (

https://github.com/openai/openai-agents-python/compare/...

). Do not use

${GITHUB_REPOSITORY}

or any other template variable. Format risk levels as bold emoji labels: 🟢 LOW, 🟡 MODERATE, 🔴 HIGH.

Every risk finding must contain an actionable next step. If the report uses

**🔴 BLOCKED**

, include an

Unblock checklist

section with at least one concrete command/task and a pass condition.

undefined

所有输出必须使用英文。

每次使用本Skill生成的响应都必须遵循以下报告结构。结论要主动且明确：在报告顶部清晰给出发布/阻塞的结论，并为每个发现分配明确的风险等级（低/中/高），同时附上简短的影响说明。当风险较低且测试已通过时，避免过度谨慎的模糊表述。

差异部分必须使用固定的仓库URL（

https://github.com/openai/openai-agents-python/compare/...

），不要使用

${GITHUB_REPOSITORY}

或任何其他模板变量。风险等级需格式化为粗体emoji标签：🟢 LOW、🟡 MODERATE、🔴 HIGH。

每个风险发现都必须包含可执行的下一步操作。若报告使用

**🔴 BLOCKED**

结论，需包含

Unblock checklist

部分，其中至少有一项具体的命令/任务及通过条件。

undefined

Release readiness review (<tag> -> TARGET <ref>)

发布就绪审查 (<tag> -> TARGET <ref>)

This is a release readiness report done by

$final-release-review

skill.

本报告由

$final-release-review

Skill生成。

Diff

差异链接

https://github.com/openai/openai-agents-python/compare/<tag>...<target-commit>

Release call:

发布结论:

<🟢 GREEN LIGHT TO SHIP | 🔴 BLOCKED> <one-line rationale>

<🟢 GREEN LIGHT TO SHIP | 🔴 BLOCKED> <一句话理由>

Scope summary:

范围摘要:

<N files changed (+A/-D); key areas touched: ...>

<修改了N个文件（新增A个/删除D个）；重点修改区域：...>

Risk assessment (ordered by impact):

风险评估（按影响程度排序）:

<Finding title>
- Risk: <🟢 LOW | 🟡 MODERATE | 🔴 HIGH>. <Impact statement in one sentence.>
- Evidence: <specific diff/test/commit signal; avoid generic statements>
- Files: <path(s)>
- Action: <concrete next step command/task with pass criteria>
...

<发现标题>
- 风险等级: <🟢 LOW | 🟡 MODERATE | 🔴 HIGH>. <一句话影响说明>
- 证据: <具体的差异/测试/提交信号；避免通用表述>
- 文件: <路径>
- 行动: <具体的下一步命令/任务及通过条件>
...

Unblock checklist (required when Release call is BLOCKED):

解除阻塞检查清单（仅当发布结论为阻塞时需要）:

<concrete check/fix>
- Exit criteria: <what must be true to unblock>
...

<具体的检查/修复任务>
- 通过条件: <解除阻塞必须满足的条件>
...

Notes:

备注:

<working tree status, tag/target assumptions, or re-run guidance>


If no risks are found, include a “No material risks identified” line under Risk assessment and still provide a ship call. If you did not run local verification, do not add a verification status section or use it as a release blocker; note any assumptions briefly in Notes.
If the report is not blocked, omit the `Unblock checklist` section.

<工作树状态、标签/目标提交的假设、或重新运行的指导>


若未发现风险，需在风险评估部分添加“未发现重大风险”的内容，并仍需给出发布结论。若未在本地执行验证，不要添加验证状态部分，也不要将其作为发布阻塞的理由；可在备注中简要说明相关假设。
若报告未判定为阻塞，可省略`解除阻塞检查清单`部分。

Resources

资源

```
scripts/find_latest_release_tag.sh
```
: Fetches remote tags and returns the newest tag matching a pattern (default
```
v*
```
).
```
references/review-checklist.md
```
: Detailed signals and commands for spotting breaking changes, regressions, and release polish gaps.

```
scripts/find_latest_release_tag.sh
```
: 拉取远程标签，并返回匹配指定模式的最新标签（默认模式为
```
v*
```
）。
```
references/review-checklist.md
```
: 用于识别破坏性变更、回归问题及发布完善空间的详细信号和命令。