mcpField
W
writing-pr

writing-pr

github.com/e2e-inc开发13.8k274 次安装今天更新
代码仓库

关于 writing-pr

用于撰写简洁、注重证据的 Pull Request 标题和正文的仓库技能，帮助贡献者清楚说明变更与验证结果，避免复述差异内容。

主要功能

  1. 01遵循 Conventional Commits 的标题
  2. 02以变更结果为标题重点
  3. 03用项目符号概述变更
  4. 04提供图表和代码示例指引
  5. 05要求附上验证证据

适用场景

  1. 01撰写代码变更的 PR
  2. 02为视觉变更整理前后对比证据
  3. 03概述基准测试或 API 变更

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/e2e-inc/e2e --skill writing-pr

安装后在 Claude Code 中输入/writing-pr确认已加载。

详细介绍

编写 PR 标题和正文

评审者通常会快速浏览。先在首屏说明变更的大致内容，再用图表和代码呈现细节。

标题

  • 使用 Conventional Commits，格式与 git log 一致： fix(playwright): provision the browser in a runner-side prepare hook。 PR 会以 squash merge 合并，并在标题后附加编号，因此标题就是提交信息。
  • 如果规范或 API 有破坏性变更，用 ! 标记（feat(config)!: ...），与提交信息一致。
  • 写明结果，而不是活动。“使用 appPath 选项构建安装包”，而不是“agent-device 变更”。

正文

不要写长篇大论。用几个要点说明改了什么、为什么改，然后提供证据。

  • 正文说明使用项目符号，每个要点只讲一件事。
  • 对于包含流程或状态的内容，使用 mermaid 图表：运行器阶段、引擎钩子、回放路径、变更前后的架构。
  • 代码示例：新 API、测试文件中的示例用法，或关键内部代码片段。使用带语言标签的围栏代码块。
  • 使用代码引用（packages/e2e/src/run/execute.ts:42、GitHub 永久链接），不要改写代码内容。
  • 对于直接或间接的视觉变更（CLI 输出、报告器输出、文档页面），提供包含上传图片或视频的前后对比表。
  • 提供基准测试：使用前后对比表。基准是目标分支，候选项是 PR。
  • 对于规范变更，在同一个要点中写明章节、架构和 suiteVersion 更新，方便评审者一并核对。
  • 如果 PR 解决了问题，添加 ## Issue 章节并写上 Fixes #123。 社区提交的 fix、chore、test、perf、ci、build 和 revert 类型 PR 必须添加此章节（CONTRIBUTING.md，Pull requests）。
  • 每个 PR 都必须添加 ## Verified 章节：
    • 第一行写：Ran it locally: yes，或 Ran it locally: no - <原因> （文档笔误、仅限 CI、没有相应设备）。
    • 如果写 yes：说明 verify 范围、运行的命令、观察到的结果，以及能证明功能正常的 CLI 输出、截图或视频。
    • 如果是 fix PR 且写了 yes，还要在 | main | this branch | 表格中并列展示问题和修复结果。
    • 使用 gh 2.99+ 的 --attach 上传媒体：在正文中以 Markdown 引用图片（![after](./after.png)），并将每个文件作为 --attach 参数传入；gh 会上传文件并重写这些路径。不要在正文中写视频路径：附加的视频会追加到末尾，并以播放器形式呈现。

不要写

  • “我运行了 lint/tests”之类的列表。CI 会报告这些内容；## Verified 用于说明 CI 无法检查的内容。
  • 中间过程。将 6k 行压缩成 1k 行、重构两次、中途重命名：这些都不会进入最终结果。最终只会有一个 squash merge 提交，因此只需说明该提交的内容。
  • 逐行复述差异内容。
  • 无人要求的检查清单、签署声明和填充内容。

模板

视觉内容的前后对比：

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

修复的验证内容（本地图片路径会通过 --attach 转为已上传的资源）：

## 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 |
| --- | --- |
| ![bug](./main.png) | ![fixed](./branch.png) |

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

基准测试：

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

流程：

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

大型变更

对于真正令人瞩目、难度高、风险高或范围广的变更，可以将正文写成技术博客：介绍背景、问题、方案、代码示例、图表、前后对比和图片。在这里讲故事也可以。但仍须遵守以上规则：运行结果只能作为 ## Verified 证据，不要写中间过程。

语气

发布前，对最终文本执行 unslop 检查。 需要注意的 PR 特征：

  • “This PR introduces...”、“comprehensive”、“robust”、“seamless”、“ensures”、“leverages”、“enhances”。
  • 用粗体标签列出内容，却只是重复该行的意思（**Performance:** Performance...）。
  • 使用长破折号。改用逗号、冒号或另起一句。
  • 为了凑三个而补足到三个的项目符号。
  • 可以原封不动贴到其他代码仓库 PR 中的摘要。

评论

支持 Markdown