掌握 tldraw 仓库的 Pull Request 编写规范：从标题、描述到录制 Before/After 视频的完整指南-港品优选

掌握 tldraw 仓库的 Pull Request 编写规范：从标题、描述到录制 Before/After 视频的完整指南

【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. World's best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw

导读

本文系统讲解 tldraw 开源仓库中编写 Pull Request（PR）的标准与实战流程，涵盖语义化标题格式、以审阅者为中心的描述撰写原则、bugfix/improvement 专用模板、交互录制视频的制作方法，以及注释清扫、API changes 表、Code changes 表等一整套发布前检查清单。读完本文，你将掌握一套可复制的 PR 内容规范，能够写出让审阅者快速理解意图、显著减少来回沟通的高质量 PR。

该规范收录于仓库的 skills/write-pr/SKILL.md，属于 Agent 技能（skill）体系中的内容标准参考文档，供其他工作流（如 skills/pr/SKILL.md 中的建 PR/改 PR 流程）引用，而非面向用户的创建/更新 PR 的交互式流程。

为审阅者而写（先读这一节）

这是统领全文的规则，其余所有要求都服务于它：PR 描述是写给一位熟悉代码库架构、但还没有读过你的代码和 diff 的审阅者的。审阅者的时间是最稀缺的资源，描述的唯一职责是提供他们从代码里无法获得的信息框架（framing），然后让开——不要替他们复述代码。

默认要短

几句话的背景交代是常态而非例外。描述的长度应与改动匹配：

一行修复对应一句话；
一个新系统才值得更完整的描述。

看起来又长又有结构的描述并不更有价值——往往更糟，因为结构本身把关键信息埋没了。如果审阅者需要再找一个 AI 来解读你的描述，这份描述就是失败的。

从粗到细，倒金字塔结构

把描述组织成倒金字塔，最重要的信息在最前面。读者可以在任何位置停下来，并带走一个正确、连贯的理解：

只扫一眼的人，从前几行就能得到目标与动机；
权衡方案的人，继续读设计与决策；
细致的审阅者，再深入到具体细节。

永远不要让任何人读到结尾才知道这个 PR 是干什么的。

按大致顺序覆盖以下层次——每一层都比上一层更详细，且一旦改动不再需要，每一层都是可选的：

目标、动机与使用场景：为什么做这个改动、为什么是现在、它有什么用，改动之前缺什么或错在哪里。这一层永远排第一。
更高层的改动：解决方案的形态——行为与结构层面，而不是对 diff 的逐行复述。
API 设计与决策：新增或变更的公共面、你选择的方案、你排除的方案及原因、以及任何你不确定的地方。一个你没有呈现出来的决策，就是审阅者无法审查的决策。
示例片段与细节：凡是涉及 API、数据形态或使用模式的改动，几行 before/after 比一段话更有效，保持最小化。

不要做的事

不要复述 diff：不做逐文件讲解、不叙述某个函数做了什么、不一步一步描述代码是如何工作的——审阅者自己会读代码。
不要生成镜像代码的表格或列表：比如逐条复述函数签名的Method | Description表、列出每个改动文件的清单、给不言自明的名字做术语表。
不要用仪式感填充：看起来像那么回事、实则只是摆设的结构都是噪音。

永远不要编造"为什么"

动机与权衡必须来自真实意图——提交记录、关联的 issue，或作者本人。如果你不知道改动为什么发生、考虑过什么方案，去问用户，不要猜。一个自信但虚构的理由比没有更糟：它具有误导性，而且是审阅者最需要信任的东西。

PR 标题

使用语义化 PR 标题（Conventional Commits 格式）：

<type>(<scope>): <description>

类型（Types）

类型	含义
`feat`	新功能
`fix`	修复 bug
`docs`	仅文档
`refactor`	既不修 bug 也不加功能的代码改动
`perf`	性能改进
`test`	新增或修复测试
`chore`	维护性任务

可选作用域（Scope）

一个描述受影响区域的普通名词：fix(editor):、feat(sync):、docs(examples):。

示例

feat(editor): add snap threshold configuration option
fix(arrows): correct binding behavior with rotated shapes
docs: update sync documentation
refactor(store): simplify migration system

这些示例中的技术点均可在仓库中找到对应实现，例如 snap 阈值相关逻辑见 SnapManager.test.ts、箭头绑定行为见 TLArrowShape.ts、迁移系统见 migrate.ts 与 StoreSchema.ts——这恰好印证了标题中的 scope 应指向真实的代码区域。

PR 主体（PR body）

Bug 修复与改进类 PR（bugfix和improvement两种 change type）使用下面的 before/after 模板，其余类型的 PR 使用通用模板。

通用模板

<description paragraph> ### Change type - [x] `bugfix` | `improvement` | `feature` | `api` | `other` ### Test plan 1. Step to test... 2. Another step... - [ ] Unit tests - [ ] End to end tests ### Release notes - Brief description of changes for users

描述段落（Description paragraph）

以 "In order to X, this PR does Y." 开头，并遵循上文"为审阅者而写"的规则。

X 是使这次改动成为必要的具体情境——某个人真正尝试做的事——而不是对 Y 做了什么的重述。"In order to let apps carry undo history across editor rebuilds, this adds an API to carry undo history across editor rebuilds" 是循环论证：X 只是给 Y 换了个说法。要把 X 向上推一层，指向真正的目标，例如 "so desktop can reload the editor without losing the user's place, the way HMR preserves component state across a code edit."
说出真实驱动案例，而不是假设场景。如果你在发明示例来说明"为什么"（"e.g. if someone toggled a plugin…"），说明你在从写好的代码倒推理由——你没有记录真正促成它的那个案例。要顺着那个案例正向写。
警惕用抽象机制替代动机。关于 SDK 的真实技术事实（"editor config is fixed at construction time"）解释的是一个约束，而不是为什么有人在意它。继续往下写，直到读者能具体想象出"什么东西坏了"或"什么东西变得可能了"。
保持具体，避免 "improve user experience" 这类含糊说法。
在第一段就链接相关 issue。
不要指望读者还去读被链接的 issue。

Bug fix 与 improvement 专用模板

Bug 修复与改进类 PR 使用固定结构而非描述段落。同样的"审阅者优先"规则适用；该结构存在的意义是让审阅者不看 diff 就能看出：之前错在哪（或缺什么）、现在做了什么、以及为什么。

This PR fixes a bug where <symptom a user or developer would hit>. ### Before <what the code did and why that produced the symptom> ### After <what the code does now> ### Implementation notes <optional: what exactly changed and how — decisions, trade-offs, anything non-obvious> ### Change type - [x] `bugfix` | `improvement` ### Test plan - [x] Unit tests — the new test fails on `main` and passes with this change ### Release notes - Fix <symptom> | Improve <behavior> ### Code changes | Section | LOC change | | --------- | ---------- | | Core code | +10 / -2 | | Tests | +5 / -0 |

各段写作要点：

Intro（一句话）：对 bug，写成 "This PR fixes a bug where X"，X 是可观察的症状，而不是原因或修复本身；对改进，写成 "This PR improves X so that Y"，Y 是用户或开发者现在可以做的事。有 issue 就在这里链接。如果 PR 不止一件事，用第二句话（"It also ..."）而不是列表。
Before：之前的行

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析