掌握 tldraw 仓库的 Pull Request 编写规范从标题、描述到录制 Before/After 视频的完整指南【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw导读本文系统讲解 tldraw 开源仓库中编写 Pull RequestPR的标准与实战流程涵盖语义化标题格式、以审阅者为中心的描述撰写原则、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修复 bugdocs仅文档refactor既不修 bug 也不加功能的代码改动perf性能改进test新增或修复测试chore维护性任务可选作用域Scope一个描述受影响区域的普通名词fix(editor):、feat(sync):、docs(examples):。示例feat(editor): add snap threshold configuration optionfix(arrows): correct binding behavior with rotated shapesdocs: update sync documentationrefactor(store): simplify migration system这些示例中的技术点均可在仓库中找到对应实现例如 snap 阈值相关逻辑见 SnapManager.test.ts、箭头绑定行为见 TLArrowShape.ts、迁移系统见 migrate.ts 与 StoreSchema.ts——这恰好印证了标题中的 scope 应指向真实的代码区域。PR 主体PR bodyBug 修复与改进类 PRbugfix和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 users 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 XX 是可观察的症状而不是原因或修复本身对改进写成 This PR improves X so that YY 是用户或开发者现在可以做的事。有 issue 就在这里链接。如果 PR 不止一件事用第二句话It also ...而不是列表。Before之前的行【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考