mcpField
W
writing-pr

writing-pr

github.com/tester-army开发12.1k273 次安装今天更新
代码仓库

关于 writing-pr

为贡献者提供撰写 PR 标题和正文的规范，强调先说明变更结果，并用图表、代码和验证证据辅助审阅。

主要功能

  1. 01遵循 Conventional Commits 标题格式
  2. 02以变更结果而非操作命名
  3. 03用要点说明改动与原因
  4. 04按需加入图表、代码和视觉证据
  5. 05规定每个 PR 的验证信息

适用场景

  1. 01整理便于审阅的 PR 标题和正文
  2. 02记录含流程或状态变更的架构图
  3. 03为修复提交前后对照证据
  4. 04编写符合仓库要求的验证部分

安装

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

$npx skills add https://github.com/tester-army/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