writing-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing a PR title and body

编写 PR 标题和正文

Reviewers skim. Put the shape of the change on the first screen, then let diagrams and code carry the detail.

审阅者只会快速浏览。先在首屏说明变更的整体情况，再通过图表和代码呈现细节。

Title

标题

Conventional Commits, matching
```
git log
```
:
```
fix(playwright): provision the browser in a runner-side prepare hook
```
. PRs squash-merge with the number appended, so the title is the commit.
Mark spec or API breaks with
```
!
```
(
```
feat(config)!: ...
```
), same as the commit.
Name the outcome, not the activity. "install builds with the appPath option", not "agent-device changes".

使用 Conventional Commits，并与
```
git log
```
保持一致：
```
fix(playwright): provision the browser in a runner-side prepare hook
```
。 PR 以 squash merge 方式合并时会附加编号，因此标题就是 commit。
与 commit 一样，使用
```
!
```
标记 spec 或 API 的破坏性变更（
```
feat(config)!: ...
```
）。
描述结果，而不是操作。应写“安装构建支持 appPath option”，不要写“agent-device 变更”。

Body

正文

Do not write essays. A few bullets on what changed and why, then evidence.

Bullet points for the prose you do write. One fact per bullet.
A mermaid diagram for anything with flow or state: runner phases, engine hooks, replay paths, before/after architecture.
Code samples: the new API, sample usage in a test file, or the key internal snippet. Fenced blocks with a language tag.
Code refs (
```
packages/e2e/src/run/execute.ts:42
```
, GitHub permalinks) instead of paraphrasing code.
Visual changes, direct or indirect (CLI output, reporter output, docs pages): a before/after table with uploaded images or videos.
Benchmarks: a before/after table. Baseline is the target branch, candidate is the PR.
Spec changes: name the chapter, schema, and
```
suiteVersion
```
bump in one bullet so the reviewer can check them together.
A
```
## Verified
```
section, required on every PR:
- First line:
```
Ran it locally: yes
```
  , or
```
Ran it locally: no - <why>
```
  (docs typo, CI-only, a device you do not have).
- With
```
yes
```
  : the verify surface, the command you ran, what you saw, and the CLI output, screenshots, or video showing it work.
- A
```
fix
```
  PR with
```
yes
```
  also shows the bug and the fix side by side in a
```
| main | this branch |
```
  table.
- Upload media with
```
gh
```
  2.99+
```
--attach
```
  : reference images in the body as markdown (
```
![after](./after.png)
```
  ) and pass each file as
```
--attach
```
  ;
```
gh
```
  uploads them and rewrites those paths. Do not write video paths in the body: attached videos are appended at the end and render as players.

不要写长篇文章。用几个要点说明变更了什么以及为什么变更，然后提供证据。

所写正文使用项目符号。每个要点只写一个事实。
凡涉及流程或状态的内容，都应使用 mermaid 图表：runner 阶段、engine hooks、replay 路径、变更前后的架构。
代码示例：新 API、测试文件中的用法示例，或关键内部代码片段。使用带语言标签的围栏代码块。
使用代码引用（
```
packages/e2e/src/run/execute.ts:42
```
、GitHub permalink），不要转述代码。
对于直接或间接的视觉变更（CLI 输出、reporter 输出、文档页面），提供包含上传图片或视频的前后对比表。
基准测试：提供前后对比表。基线是目标分支，候选版本是该 PR。
Spec 变更：在一个要点中写明章节、schema 以及
```
suiteVersion
```
的版本升级，以便审阅者一并核查。
每个 PR 都必须包含
```
## Verified
```
部分：
- 第一行：
```
Ran it locally: yes
```
  ，或
```
Ran it locally: no - <why>
```
  （文档拼写错误、仅限 CI、你没有相应设备）。
- 若为
```
yes
```
  ：说明 verify 界面、运行的命令、观察到的结果，以及证明其正常工作的 CLI 输出、截图或视频。
- ```
fix
```
  类型的 PR 若为
```
yes
```
  ，还要在
```
| main | this branch |
```
  表格中并排展示 bug 和修复结果。
- 使用
```
gh
```
  2.99+ 的
```
--attach
```
  参数上传媒体：在正文中以 markdown（
```
![after](./after.png)
```
  ）形式引用图片，并通过
```
--attach
```
  传入每个文件；
```
gh
```
  会上传文件并重写这些路径。不要在正文中写视频路径：上传的视频会追加到末尾，并渲染为播放器。

Leave out

不应包含

"I ran lint/tests" lists. CI reports that;
```
## Verified
```
is for what CI cannot see.
Intermediate history. Squashed 6k lines down to 1k, refactored twice, renamed midway: none of it lands. Only the final aggregate squash-merge commit exists, so only that gets commentary.
Line-by-line restating of the diff.
Checklists nobody asked for, sign-offs, filler.

“我运行了 lint/tests”之类的列表。CI 会报告这些内容；
```
## Verified
```
用于记录 CI 看不到的信息。
中间过程。将 6k 行压缩到 1k 行、重构两次、中途重命名：这些内容都不会进入最终结果。最终只存在聚合后的 squash-merge commit，因此只需对它进行说明。
逐行复述 diff。
没人要求的 checklist、签署确认或填充内容。

Templates

模板

Before/after for visuals:

markdown

| Before | After |
| --- | --- |
| ![before](url) | ![after](url) |

Verified, for a fix (local image paths become uploaded assets with

--attach

markdown

undefined

视觉变更的前后对比：

markdown

| Before | After |
| --- | --- |
| ![before](url) | ![after](url) |

修复类 PR 的 Verified（使用

--attach

后，本地图片路径会转换为上传资源）：

markdown

undefined

Verified

Ran it locally: yes

testbed,
```
e2e run tests/scroll.e2e.ts --video
```
: the new test fails on main and passes here

main	this branch


`gh pr edit <pr> --body-file body.md --attach ./main.png --attach ./branch.png --attach ./video.webm`

Benchmarks:

```markdown
| Scenario | main | this PR | delta |
| --- | --- | --- | --- |
| testbed default suite | 41s | 23s | -44% |

Flow:

markdown

```mermaid
flowchart LR
  A[collect] --> B[schedule]
  B --> C{cache hit?}
  C -- yes --> D[replay]
  C -- no --> E[act]
```

Ran it locally: yes

testbed,
```
e2e run tests/scroll.e2e.ts --video
```
: the new test fails on main and passes here

main	this branch


`gh pr edit <pr> --body-file body.md --attach ./main.png --attach ./branch.png --attach ./video.webm`

基准测试：

```markdown
| Scenario | main | this PR | delta |
| --- | --- | --- | --- |
| testbed default suite | 41s | 23s | -44% |

流程：

markdown

```mermaid
flowchart LR
  A[collect] --> B[schedule]
  B --> C{cache hit?}
  C -- yes --> D[replay]
  C -- no --> E[act]
```

Big changes

大型变更

For truly impressive, difficult, high-risk, or wide-scoped changes, write the body like a technical blog post: context, the problem, the approach, code samples, diagrams, before/after, images. Storytelling is fine here. The rules above still hold: run output only as

## Verified

evidence, no intermediate history.

对于真正令人印象深刻、难度高、风险高或范围广的变更，正文应像技术博客文章：包括背景、问题、方案、代码示例、图表、变更前后对比和图片。这里可以采用叙事方式。上述规则仍然适用：运行输出只能作为

## Verified

中的证据，不写中间过程。

Voice

语气

Run the unslop pass on the final text before posting. PR-specific tells to catch:

"This PR introduces...", "comprehensive", "robust", "seamless", "ensures", "leverages", "enhances".
Bold label lists that restate the line (
```
**Performance:** Performance...
```
).
Em dashes. Use a comma, a colon, or a new sentence.
Bullets padded to three because three felt right.
A summary that could be pasted unchanged into another repo's PR.

发布前，对最终文本执行一次 unslop 检查。需要避免以下 PR 特有表述：

“This PR introduces...”、“comprehensive”、“robust”、“seamless”、“ensures”、 “leverages”、“enhances”。
加粗标签列表只是在重复所在行的内容（
```
**Performance:** Performance...
```
）。
Em dash。改用逗号、冒号或另起一句。
为了凑成三条而添加的项目符号。
可以直接原样粘贴到另一个仓库 PR 中的摘要。