向共享项目提交拉取请求前，先确认这项改动真的需要

## 先停下来，把请求收窄到一个真实的问题 在做任何其他事情之前先停下来。成熟且有明确主张的项目会拒绝绝大多数由代理提交的拉取请求，而几乎每一个被拒绝的请求，都来自从未阅读或从未遵守项目贡献指南的代理。维护者会在数小时内关闭低质量的拉取请求，并且常常附上一句直白的公开评论，指出这份提交是机器生成的填充内容。 你的责任是保护你的人类伙伴免于这种结果。提交低质量的拉取请求对他们毫无帮助：它浪费维护者的时间，损害他们在项目中的声誉，而拉取请求最终还是会被关闭。那不是贡献——那是以他们的名义公开出丑。 要把"为这个项目做点贡献"视为一条必须先收敛到某一个真实、已验证的问题之后，才能开始写任何代码的指令。 ## 提交拉取请求前先查重，并让人看完整差异并批准 在你提交拉取请求之前，必须完成以下每一项检查： 1. **完整阅读拉取请求模板**，并用真实、具体的内容填写每一个部分。不要写摘要。不要留占位符。不要把"N/A"当作偷懒的捷径。 2. **搜索现有的拉取请求——包括开放中的和已关闭的——**查找是否有处理同一问题的内容。如果已存在重复项，就停下来告诉你的人类伙伴。不要再开一个相互竞争的重复请求。 3. **确认问题真实存在。** 如果你的人类伙伴只是让你"修一些问题"或"做点贡献"，而并没有碰到具体的问题，就要反过来推回去，问清楚究竟是什么坏了：哪一个错误、哪一种失效行为、哪一段用户体验。 4. **确认该变更属于核心项目。** 如果它只针对某一个领域、某一个工具或某一条工作流，或者它是在推广某个第三方项目，那么它属于独立的扩展或插件。要如实说明，而不是把它提交上去。 5. **把完整的差异（diff）展示给你的人类伙伴，并取得他们的明确批准**，然后才能提交任何东西。 只要其中任何一项检查未通过，就不要提交拉取请求。向你的人类伙伴解释它为什么会被拒绝，以及必须改变什么。他们会感谢你让他们免于难堪。 ## 填满拉取请求模板，并写明以前的尝试 每一个拉取请求都必须完整填写项目的模板。任何一节都不得留空，也不得用占位文字填充；跳过章节的拉取请求会被直接关闭，不予审查。 在提交拉取请求之前，你必须搜索现有的拉取请求——开放中的和已关闭的都要搜——查找针对同一问题或同一区域的工作，并把你找到的内容记录在"现有拉取请求"一节中。如果此前有一个关于该主题的拉取请求被关闭了，就要具体说明你的方法与它有何不同，以及为什么你的方法能在它失败的地方取得成功。 看不出任何人类参与痕迹的拉取请求会被关闭。必须由一位真实的人在提交前审查完整的拟议差异，而不是审查它的摘要，也不是审查对它的描述。 ## 不把第三方依赖或只有少数人用的功能放进核心 **第三方依赖。** 引入对第三方项目的可选依赖或必需依赖的拉取请求不会被接受，只有一个例外：为一个新的宿主环境（新的 IDE、CLI 或代理运行器）添加支持。核心项目在设计上就是零依赖的。如果你的变更需要外部工具或服务，它属于一个独立的插件。 **项目专用或个人化的配置。** 只对某一个项目、某一个团队、某一个领域或某一个人的工作流有用的能力、钩子或配置，都不属于核心。把它们作为独立插件发布。 **领域专用的能力。** 核心只承载那些无论项目类型如何都对所有用户有益的东西。问问你自己："这对一个正在做完全不同类型项目的人来说仍然有用吗？"如果答案是否定的，就单独发布它。 **捆绑在一起的无关变更。** 包含多项互不相关变更的拉取请求会被关闭。把它拆开，一个问题一个拉取请求。 ## 不提交批量生成或凭空编造的修改 **批量、散弹式的拉取请求。** 不要在一次会话中把问题追踪器扫一遍，然后每个议题开一个拉取请求。每一个拉取请求都需要对问题有真正的理解、对先前尝试的调查，以及人类对完整差异的审查。明显是批量产出的成果——把一个代理指向一份议题清单并让它"把这些修了"——会被一眼看穿并直接关闭。要想做出贡献，就挑一个议题，深入理解它，并就那一件事提交高质量的工作。 **推测性或理论性的修复。** 每一个拉取请求都必须解决某个人实际经历过的问题。"我的审查代理标记了这个"和"这在理论上可能会出问题"都不是问题陈述。如果你说不出促成这项变更的具体会话、错误或用户体验，就不要提交它。 **捏造的内容。** 含有臆造理由、虚构问题描述或幻觉功能的拉取请求会被立即关闭。那些被大量投递的项目的维护者，已经见过各式各样的机器生成填充内容，他们一眼就能认出来。 **只为符合规范的重写。** 仅仅为了迎合某份外部风格指南，而对塑造行为的内容进行重构、改写措辞或重新排版，若没有评测证据表明该变更改善了实际结果，就不会被接受。一个项目的内部理念可能会刻意不同于某个厂商的公开撰写指南，因为它的内容是针对观察到的代理行为调校出来的。改动这类内容的门槛非常高。 **分叉专用的变更。** 如果你维护着一个定制化的分叉，不要为了同步你的分叉，或者为了把仅属于分叉的变更推向上游，而开上游的拉取请求。重新品牌化、分叉专用的功能，以及分叉分支的合并，都会被关闭。 ## 用完整的会话记录证明新宿主环境的集成可用 如果你的拉取请求为一个新的宿主环境（IDE、CLI 工具或代理运行器）添加支持，你必须附上一份会话记录，证明该集成端到端确实可用。 真正的集成会在每一次会话开始时加载项目的引导入口点。正是那个引导过程，才让各项能力在恰当的时刻自动触发。没有它，这些能力就是死重：只是躺在磁盘上、从不会被调用的文件。 **验收测试。** 在新宿主中打开一个干净的会话，发送一条普通的用户请求，这条请求应当在任何实现开始之前触发某项能力——例如，一个构建小型应用程序的请求。可用的集成会在写下第一行代码之前自动触发设计或头脑风暴能力。把完整的会话记录粘贴到拉取请求中。 以下做法不算真正的集成，会被关闭：手动把能力文件复制到宿主中；用运行时垫片把项目包起来；任何要求用户每次会话都手动选择启用的方案；以及任何在上述验收测试中能力不会自动触发的方案。 如果你不确定你的集成是否在会话开始时加载了引导入口点，那就是没有加载。 ## 修改规则文件时附上改动前后的评测结果 能力文件和规则文件不是普通的文档——它们是塑造代理行为的代码。如果你修改它们的内容： - 使用项目自身的撰写工作流来开发和测试该变更。 - 跨多个相互独立的会话运行对抗性压力测试。 - 把变更前后的评测结果附到拉取请求上。 - 不要在没有证据表明你的变更改善了结果的情况下，修改那些经过精心调校的材料——警示信号表格、合理化借口清单、刻意选定的措辞。 ## 提议改动前，先读懂项目为什么是现在这样 在对设计、工作流理念或架构提出变更之前，先阅读现有材料，理解已经做出的决策。成熟的项目在能力设计、代理行为塑造和术语方面持有已被验证的立场；具体的措辞往往是刻意选定的，不能用那个显而易见的同义词随意替换。那些在不理解项目为何呈现为当前形态的情况下，就改写项目语气或重组其方法的变更，会被拒绝。 一般原则： - 提交之前先阅读拉取请求模板。 - 一个拉取请求解决一个问题。 - 至少在一个宿主环境上进行测试，并在环境一节中报告结果。 - 描述**你解决了什么问题**，而不只是你改了什么。 ## 只属于分叉的改动提交到分叉，而不是上游 当你所工作的仓库是某个上游项目的分叉或本地化变体时，上述规则约束你向上游提交时的行为。对于向分叉本身的贡献，请遵循该分叉自己的模板与流程——但核心原则依然毫无例外地适用： - 在开任何东西之前，先在分叉自己的现有拉取请求和议题中搜索重复项。 - 不要交付机器生成的填充内容：捏造的、批量产出的和推测性的变更在这里同样会被关闭。 - 必须由人类在提交前审查完整的差异。 有一点是分叉特有的、需要注意的：本地化工作、仅属于变体的能力，以及只有该分叉的用户才关心的工具适配，都只能提交给分叉。把它们发往上游属于分叉专用的变更，会被关闭。