别让第一个好点子死在空白输入框里:vibe 项目的 Issue/PR 模板与贡献指南实战
好点子不是没人愿意帮忙,而是死在了空白输入框里。本篇讲 Issue 表单、PR 模板与 CONTRIBUTING.md 怎么做,让第一次投稿就交出能直接评审的东西。本篇走查示例中的项目、人物与数字均为虚构。

你的 vibe 项目开源了,第一个星期来了 3 颗星,第二个月有人提了第一个 issue:“这个功能不好用。”你点开一看,标题只有四个字,正文一片空白——哪个功能?怎么不好用?在什么设备上?你追问了两句,对方再也没回。第三个月有人提了第一个 PR:改了 40 个文件、2000 多行,没有描述、没有测试、没有关联 issue,你花了一晚上读代码,最后只能关掉,心里还过意不去。问题不是没人愿意帮忙,是帮忙的路太难走:投稿入口是一片空白输入框,贡献者不知道你想要什么,你也不知道对方交上来的是什么。
先说清楚两件事。第一,本篇里的走查项目“松果笔记”、维护者“阿松”、贡献者“小北”,以及所有时间、数量数字全部是虚构的,只是为了把流程讲明白而编的例子。第二,划界:本站已经发过《别让第一个 PR 死在 README 里:AI 生成仓库的新人贡献者上手手册》,那篇讲的是新人怎么走进仓库、跑起来、交出第一份贡献;也发过《Star 之后呢:vibe 项目的开源仓库运营实战》,那篇讲的是 Star 之后的仓库运营,包括 Issue 分诊流水线;还发过开源发布指南和开源协议指南,讲的是发布和选协议。本篇不重复那几篇,只讲一件事——投稿漏斗的入口怎么做:Issue 模板、PR 模板和 CONTRIBUTING.md,让每一个想帮忙的人,第一次投稿就交出你能直接用的东西。

一、先看漏斗:帮忙的人都在哪一步流失
做模板之前,先把投稿的路画出来。从“想提点什么”到“合进主线”一共五步:打开模板选择器、提交 issue 或 PR、信息完整到能评审、进入评审、合并。漏斗的每一步都有流失点:第一步流失在“不知道该提 issue 还是直接提 PR”;第二步流失在“空白输入框不知道写什么”;第三步流失在“缺复现步骤、缺版本号,维护者没法复现”;第四步流失在“PR 太大,评审者读不下去”;第五步流失在“评审拖了两周没人理,贡献者走了”。
本篇虚构示例的漏斗数字是:100 个人打开模板选择器,70 个人提交了 issue 或 PR,45 个人的信息完整到能评审,20 个进入评审,12 个最终合并。这些数字是虚构的,用来说明一个道理:模板和 CONTRIBUTING 改善的不是最后一步的合并率,而是前三步的转化率——让更多人从“想帮忙”走到“交出能评审的东西”。如果你只盯着合并了几个 PR,会误以为问题在评审;其实大多数贡献死在第二步和第三步,死在空白输入框和信息不全里。
所以模板设计的第一条规矩是:模板是提问的艺术,不是填空题大全。好的模板只问“评审必须知道的事”,每多一个字段,就多一批在半路放弃的投稿人。Bug 报告问复现步骤、版本号、期望与实际;功能建议问问题、方案、备选方案;提问问背景、试过什么、卡在哪一步。问完了就停,不要再加“你的操作系统版本号、浏览器版本号、网络环境、时区”这种“以防万一”的字段——维护者真需要时,可以在评论里追问。
二、Issue 模板:Bug 表单、功能建议、提问分流
GitHub 的 Issue 模板有两种做法:Markdown 模板和 YAML 表单。Markdown 模板是把一段带标题的文字预填进输入框,贡献者可以随手删掉;YAML 表单是渲染成真正的表单字段,还能把某些字段设为必填,提交前不填完就交不上去。2026 年 11 月核实的 GitHub 官方文档写明:表单文件放在仓库的 .github/ISSUE_TEMPLATE 目录下,以 name、description、body 三个键开头;表单提交后,填写内容会转成 Markdown 追加到 issue 正文里;PR 不支持表单,只能用 Markdown 模板。
Bug 报告表单建议这样排(字段名是示例,可直接照抄结构):开头一段 markdown 欢迎语,写清“先搜一下有没有重复 issue”;然后是必填的 textarea“发生了什么”,提示“请贴出确切的报错信息”;必填的 textarea“复现步骤”,placeholder 里写“1. 打开…… 2. 点击…… 3. 看到……”;必填的 input“版本号”,提示填发布号或提交哈希;必填的 textarea“期望的结果”和“实际的结果”,分开两栏写,不要合成一个“问题描述”,合在一起写的人往往只写一半。顶层再配上 title: "[Bug]: " 和 labels: [bug, needs-triage],新 issue 一创建就自动带上标题前缀和待分诊标签,维护者打开列表一眼就能分类。
功能建议表单要解决另一个毛病:上来就写方案、不说问题。“加一个深色模式”后面如果不写“为什么”,维护者没法判断这个需求值不值得做,也没法在方案 A 和方案 B 之间选。所以功能建议表单的字段顺序应该是:先问“你要解决什么问题”,再问“你建议的方案是什么”,最后问“你还考虑过哪些备选方案”。三个字段都必填,但每个字段的提示语要写清标准:“问题”要写谁、在什么场景下、遇到了什么困难;“方案”要写具体改哪里;“备选方案”哪怕只写一句“没想过”也行,重点是逼投稿人先想一遍,而不是上来就交一份设计稿。
提问要单独分流,不要和 Bug 报告共用一个模板。提问模板只需要三项:背景、已经试过什么、卡在哪一步。更重要的是,模板选择器里要放一个“去讨论区提问”的链接:很多问题其实是用法问题,不值得变成一个长期挂在列表里的 issue。GitHub 的 Discussions 只支持 YAML 表单,不支持 Markdown 模板,这一点在官方文档里有明确说明。分流做得好,issue 列表里剩下的就全是真正需要修、需要做的工作,维护者每天打开列表时的心情会好很多。
最后是 config.yml 里的一个开关:blank_issues_enabled: false。关掉空白 issue,意味着贡献者必须选一个模板才能提交。刚开始做模板的项目建议先开着空白 issue 观察两周:看看不走模板的人都提了什么,如果全是模板覆盖不到的新类型,说明模板还缺一种;如果全是“我不知道怎么填”,说明模板的提示语要重写。两周之后再关掉空白 issue——关掉之前,先确认三类模板(Bug、功能建议、提问)都已就位,不然就是把投稿的门直接焊死。
三、PR 模板:让评审者五分钟读懂一份改动
PR 不支持 YAML 表单,只能用 Markdown 模板,文件放在 .github/pull_request_template.md(单个模板)或 .github/PULL_REQUEST_TEMPLATE/ 目录下(多个模板可选)。PR 模板的目标只有一个:让评审者在五分钟内判断“这份改动能不能合”。模板建议固定六段:改了什么、为什么改、怎么测的、截图或录屏、关联 issue、检查清单。每段的提示语用 HTML 注释写(<!-- ... -->),提交时注释不会出现在正文里,但填表的人能看到要求。
“改了什么”要写文件级的变化,不是“优化了代码”这种空话;“为什么改”要链到 issue 编号或需求背景,没有关联 issue 的 PR,评审者要先花半小时猜动机;“怎么测的”要写具体命令和结果,比如“跑了 pnpm test,12 个测试通过”或“手动验证了三步:……”,而不是只打勾“我已测试”;“截图或录屏”只对界面改动必填,后端改动可以写“无界面变化”;“检查清单”放四到六项就够了:测试通过、文档已更新、没有破坏性变更、已经跑过 lint。清单超过八项,投稿人就开始无脑全勾,清单也就失去了意义。
PR 模板之外,还要立一条“小 PR”规矩:本篇虚构示例的数字是,单个 PR 的改动建议不超过 300 行。超过 300 行的 PR,评审者读到一半就会放下,拖两周是常态。超过的部分怎么办?拆:先提一个只改数据结构的 PR,再提一个只改界面的 PR,依赖关系写在描述里。维护者也可以在 CONTRIBUTING 里写明:“超过 300 行的 PR 请先开个 issue 讨论拆分方案”,把大 PR 挡在提交之前,而不是合并不了之后再吵架。
草稿 PR 是另一件好用的工具:改动还没写完、想先让维护者看一眼方向对不对,就开草稿 PR,标题前自动带 WIP 标记。很多新手不知道草稿 PR 的存在,写到一半不敢提,写完了才发现方向错了——在 CONTRIBUTING 里用一句话告诉他们:“方向不确定时,先开草稿 PR 讨论,别等写完。”这句话能省掉的返工,比任何模板都多。
四、CONTRIBUTING.md:一次写清的八段话
CONTRIBUTING.md 是仓库的“新员工手册”,放在仓库根目录或 .github/ 目录下。第一次写不用追求完美,八段话就够了:快速开始、开发流程、分支命名、提交信息、测试要求、代码风格、行为准则、发版说明。快速开始要写到“复制粘贴三条命令就能跑起来”的程度,命令里不要留“安装依赖”这种含糊表述,写具体的命令和预期的输出;开发流程写“先开 issue 讨论,再 fork,再提 PR”,不要默认贡献者知道你的流程;分支命名给一个例子,比如 feat/xxx 或 fix/xxx,不要只写“请使用有意义的分支名”。
提交信息给一套最小规范就够了:动词开头、一句话说清改了什么、关联 issue 编号,比如“修复登录页在窄屏下按钮溢出的问题(#123)”。不要一上来就推 Conventional Commits 全套规范加 commitlint 强校验——对 vibe 项目来说,门槛比规范重要,先让贡献者愿意提交,再慢慢收紧。测试要求写清楚“哪些改动必须带测试”:修 Bug 要带一个复现测试,加功能要带对应的单测,改文案不用。代码风格只写三条最关键的:格式化工具和命令、命名习惯、不要留 console.log。行为准则直接引用 Contributor Covenant,写一句话加链接即可,不用全文复制——公约文本有官方版本,抄一份放进仓库反而会在版本更新时过期。
发版说明是很多 CONTRIBUTING 漏掉的一段:谁负责发版、多久发一次、版本号怎么涨。哪怕只有一句话——“维护者每月发一次版,PR 合并后不立刻发布”——也能少掉很多“我的 PR 合并了为什么线上还没更新”的追问。写完之后,把 CONTRIBUTING 的链接放到 README 的显眼位置,再在 PR 模板的检查清单里加一项“我已阅读 CONTRIBUTING”,入口、模板、文档三处互相咬合,漏斗才算真正闭合。
五、标签体系:先有共识,再谈自动化
模板交上来的 issue 还要过标签这一关。标签不是越多越好,最小集合建议 8 个:bug、enhancement、documentation、question、needs-triage、needs-info、good first issue、help wanted。每个标签配一句含义,写进 CONTRIBUTING 里:needs-triage 是“还没人看过”,needs-info 是“等投稿人补充信息”,good first issue 是“新手友好、有明确验收标准”,help wanted 是“维护者想做但没时间,欢迎接手”。含义不清的标签比没有标签更糟——同一个人今天标 bug,明天标 enhancement,后天发现列表里根本筛不出来。
good first issue 是标签体系里最值得花心思的一个。挑的原则有三条:改动范围小、验收标准明确、不需要理解整个系统架构。比如“把登录按钮的文案从‘提交’改成‘登录’”是好的 good first issue;“重构鉴权模块”不是,哪怕它看起来很简单。贴上标签之后,本篇虚构示例的数字是,7 天内会被新手认领——这个数字是虚构的,重点不是 7 天,而是“贴了标签就要有人管”:每周看一次 good first issue 列表,超过两周没人认领的,要么是题目太难,要么是描述不清,摘掉标签重写,不要让它在列表里烂掉。
标签和模板要联动:Bug 表单自动打 bug 和 needs-triage,功能建议表单自动打 enhancement 和 needs-triage,提问模板自动打 question。这三个自动标签在 YAML 表单的顶层 labels 键里配,官方文档写明了支持。自动打标签省掉的是维护者每天手动分类的时间,但也带来一个要求:标签含义必须先达成共识,否则自动化只会把混乱批量生产出来。
六、自动分诊与机器人:最小配置,不要过度自动化
模板和标签就位之后,机器人可以接手三件小事:自动打标签、自动回第一句话、过期自动提醒。自动打标签前面已经讲过。自动回第一句话是指:新 issue 创建后,机器人自动评论一句“感谢投稿!维护者会在 3 个工作日内回复”(虚构示例数字),同时贴上 CONTRIBUTING 里对应的段落链接。这句话的作用是让投稿人知道“有人收到了”,而不是“石沉大海”。但要注意:自动回复只能回这一句,不能代替人回第二句——机器人回完之后,维护者必须在承诺的时间内亲自回复,否则自动回复就成了空头支票。
过期提醒用 stale 规则:本篇虚构示例的数字是,30 天无活动的 issue 自动标 stale,再过 14 天无人回应自动关闭。stale 规则要配两句人话:标 stale 时评论一句“这个 issue 已 30 天无活动,如果仍需处理请留言”;关闭时评论一句“因长期无活动关闭,如需重开请留言”。不要静默关闭——静默关闭等于告诉投稿人“你的东西我们扔了,而且懒得告诉你”。另外,stale 不要碰三类 issue:标了 good first issue 的、标了 help wanted 的、有明确复现步骤的 Bug——这三类关掉了,损失比留着更大。
过度自动化是这一步最常见的坑。见过有项目配了 6 个机器人:自动打标签、自动指派、自动关重复 issue、自动催评审、自动发周报、自动给 PR 打分,结果是维护者每天先花半小时处理机器人留下的评论。记住一条线:机器人只做“机械的、不会错的”事——打标签、发提醒、贴链接;判断“这是不是重复 issue”“这个 PR 能不能合”这种需要理解的事,永远留给人。自动化是为了省时间,不是为了显得专业。
七、从投稿到合并:评审清单与致谢
走到评审这一步,模板的任务已经完成了,剩下的是人的工作。评审清单建议固定五项:改动是否符合 issue 里的约定、测试是否覆盖了改动、文档是否同步更新、有没有破坏性变更、代码风格是否一致。每一项都要在 PR 页面上留痕:评审者点“批准”时写一句“测试已看过,覆盖了新增分支”,而不是只点一个绿勾。留痕的意义在于,三个月后有人问“这个改动为什么这么写”,能从 PR 页面上找到答案,而不是去翻聊天记录。
合并策略对 vibe 项目推荐 squash 合并:一个 PR 压成一个提交,主线历史干净,回滚时也只要回滚一个提交。合并之后不要立刻关 issue:先确认线上验证通过,再由机器人或维护者关闭关联 issue,并在关闭评论里写清“已在 v0.4.2 发布”(虚构示例版本号)。投稿人收到这条通知,才算走完投稿的全程——很多人提完 PR 就再也不看,原因就是上一次合并之后石沉大海,不知道自己的东西到底上线没有。
最后一件容易漏的事是致谢。合并 PR 时在评论里@投稿人说一句谢谢,把名字写进 README 的贡献者名单或发布说明里,成本几乎为零,效果却是最好的留人手段。开源项目的贡献者不是员工,没有工资,能留住他们的只有两样东西:自己的东西真的上线了,以及有人认真对待了自己的东西。模板、标签、机器人,都是为了让第二件事发生得更快、更可靠。
八、上线前检查清单
照着这张清单逐项打勾,再发布这套模板。第一,模板选择器里有三类模板:Bug 报告(YAML 表单,必填复现步骤、版本号、期望与实际,自动打 bug 和 needs-triage)、功能建议(先问问题、再问方案、最后问备选方案)、提问(背景、已试过什么、卡在哪一步,附讨论区链接);空白 issue 先开两周观察再决定关不关。第二,PR 模板在 .github/pull_request_template.md,固定六段:改了什么、为什么改、怎么测的、截图或录屏、关联 issue、检查清单;小 PR 建议不超过 300 行改动;方向不确定先开草稿 PR。第三,CONTRIBUTING.md 有八段话:快速开始、开发流程、分支命名、提交信息、测试要求、代码风格、行为准则(引用 Contributor Covenant)、发版说明;链接放在 README 显眼处。第四,标签最小集合 8 个,含义写进 CONTRIBUTING;Bug 与功能建议表单自动打标签;good first issue 每周检查一次,超两周无人认领的重写或摘标。第五,机器人只做三件小事:自动打标签、自动回第一句话(承诺 3 个工作日内人工回复)、stale 提醒(30 天标 stale,再 14 天关闭,关闭前留言说明);stale 不碰 good first issue、help wanted 和有复现步骤的 Bug。第六,评审清单五项固定、评审留痕、squash 合并、合并后在发布里致谢并通知投稿人。
避坑再强调六条。第一,不要把模板当成“防止投稿”的墙:字段每多一个,投稿就少一批;只问评审必须知道的事。第二,不要用 Markdown 模板冒充表单:Markdown 模板可以被随手删掉,必填字段要用 YAML 表单。第三,不要把提问和 Bug 混在一起:用法问题进讨论区,issue 列表只留真正要修、要做的事。第四,不要让机器人代替人回第二句话:自动回复的承诺,维护者必须兑现。第五,不要静默关闭 issue:关闭前留言说明,投稿人有权知道自己的东西去哪了。第六,不要等“有人投稿了再补模板”:第一个 issue 到来之前,模板就该在仓库里等着——模板不是给已经投稿的人准备的,是给下一个想帮忙、正在犹豫要不要点开空白输入框的人准备的。

回到开篇那个被空白 issue 和 2000 行 PR 难住的维护者。装好这套模板之后,同样的一周会变成这样:有人想报 Bug,打开选择器,表单一步步问他“发生了什么、怎么复现、哪个版本”,提交时自动带上标签;有人想加功能,先写问题、再写方案;有人想提 PR,模板提醒他拆小一点、先开草稿讨论方向。你每天打开 issue 列表,看到的不再是空白正文和猜谜游戏,而是能直接评审、直接动手的东西。开源贡献的漏斗,窄口从来不在“没人愿意帮忙”,而在“想帮忙的人不知道从哪下手”。把入口修好,帮忙的人自己会走进来。
评论 (0)
相关文章
Flexbox 一次只排一个方向,排对了,导航栏、卡片墙、购物车行都听话。本文按 MDN 的《Basic concepts of flexbox》《Aligning items in a flex container》《Controlling ratios of flex items along the main axis》三篇官方文档讲清楚:两根轴、容器与项目、方向与换行、剩余空间、flex 三件套、两根轴上的对齐、间距与自动边距。
一张点单就是一个对象:桌号、菜品、总价、付没付钱,全按标签收在一起。本文按 MDN 的《Working with objects》《JSON》《Object》三篇官方文档讲清楚:对象字面量、点号与方括号、增删改查、for...in 配 hasOwn、方法与 this、getter 与 setter、引用与复制、Object.assign 等工具箱、空白原型对象、JSON 的严规矩,以及 stringify 与 parse 和数字精度的坑。
2026 年 11 月 17 日,微软发布 MAI Code 2 和 Code 2 Flash:大模型 770 亿激活参数、100 万上下文,四项基准平均通过率 63.2%,与 GPT-6.1 Sol、Claude Opus 5.5 咬得很紧,但每任务成本只有 0.309 美元。先看清三处“但是”:价格是推广价、分数是三者最低、长周期任务不在舒适区。