共建指南
这里不缺“AI 很强”之类的观点,缺的是别人能照着复现的真实过程。一次贡献最好只讲清一个问题,并带上操作、结果和边界。
内容原则
写给具体的人
每篇内容先明确读者:
- 第一次用 AI 编程的新手。
- 会写代码,但还不会让 AI 进入真实项目的开发者。
- 想把 AI 编程引入团队流程的负责人。
- 想做自动化交付的创作者。
写成可执行流程
一篇教程至少要让读者找到:
- 前置条件。
- 操作步骤。
- 命令或配置。
- 预期结果。
- 常见失败。
- 验证方式。
写出边界
不要只写“推荐这样做”。把适用条件、不能覆盖的范围和验收方式一起写出来。
提交流程
- 新建分支。
- 修改
docs/下的文档。 - 本地运行
npm run build。 - 提交 PR。
- 等待 GitHub Actions 通过和维护者安排评审。
- 只有在 PR 进入处理队列后,按维护者要求同步目标分支或 rebase。
PR 排队与 rebase
PR 遇到“分支落后”或“可能需要 rebase”,不代表作者现在就要处理。 是否 rebase,要结合合并顺序、依赖关系和当前评审阶段判断。
先判断是不是现在的问题
- 只是分支落后,但 PR 还没有排到评审或合并队列:可以先不动。
- 多个 PR 正在修改同一片区域:先由维护者安排顺序,避免作者反复 rebase。
- PR 即将评审、合并,或者已经出现实际冲突:这时再要求作者同步目标分支。
- CI、分支保护规则或项目维护者明确要求最新基线:按要求处理,并说明原因。
rebase 会消耗贡献者的时间,而且一次 rebase 可能会因为前置 PR 的合并而很快失效。因此, 要求 rebase 的人应该是了解合并顺序、并且即将处理这个 PR 的维护者,而不是看到状态变化就立刻发出统一提醒。
推荐的沟通方式
如果 PR 还没有排到处理顺序,可以直接说明:
这个 PR 已经排进队列,目前不需要 rebase。等它进入评审/合并阶段后,我会通知你同步目标分支。
如果现在确实需要作者操作,应同时说明触发条件:
这个 PR 现在进入评审顺序了,目标分支已经合并了相关改动。请基于最新目标分支 rebase,解决冲突后重新运行检查。
核心原则是:发现技术问题,不等于立即要求别人行动;先确认时机、顺序和提出要求的权限。
这条规则来自一次真实的开源协作纠偏,完整经过见PR 有冲突,也不代表现在就要处理。
文档风格
- 标题直接说主题。
- 段落短一点。
- 命令必须可复制。
- 风险和前提要写清楚。
- 写清真实失败、判断依据和修正过程,不用成功学句子收尾。