Skip to content

共建指南 ​

这里不缺“AI 很强”之类的观点,缺的是别人能照着复现的真实过程。一次贡献最好只讲清一个问题,并带上操作、结果和边界。

内容原则 ​

写给具体的人 ​

每篇内容先明确读者:

  • 第一次用 AI 编程的新手。
  • 会写代码,但还不会让 AI 进入真实项目的开发者。
  • 想把 AI 编程引入团队流程的负责人。
  • 想做自动化交付的创作者。

写成可执行流程 ​

一篇教程至少要让读者找到:

  • 前置条件。
  • 操作步骤。
  • 命令或配置。
  • 预期结果。
  • 常见失败。
  • 验证方式。

写出边界 ​

不要只写“推荐这样做”。把适用条件、不能覆盖的范围和验收方式一起写出来。

提交流程 ​

  1. 新建分支。
  2. 修改 docs/ 下的文档。
  3. 本地运行 npm run build。
  4. 提交 PR。
  5. 等待 GitHub Actions 通过和维护者安排评审。
  6. 只有在 PR 进入处理队列后,按维护者要求同步目标分支或 rebase。

PR 排队与 rebase ​

PR 遇到“分支落后”或“可能需要 rebase”,不代表作者现在就要处理。 是否 rebase,要结合合并顺序、依赖关系和当前评审阶段判断。

先判断是不是现在的问题 ​

  • 只是分支落后,但 PR 还没有排到评审或合并队列:可以先不动。
  • 多个 PR 正在修改同一片区域:先由维护者安排顺序,避免作者反复 rebase。
  • PR 即将评审、合并,或者已经出现实际冲突:这时再要求作者同步目标分支。
  • CI、分支保护规则或项目维护者明确要求最新基线:按要求处理,并说明原因。

rebase 会消耗贡献者的时间,而且一次 rebase 可能会因为前置 PR 的合并而很快失效。因此, 要求 rebase 的人应该是了解合并顺序、并且即将处理这个 PR 的维护者,而不是看到状态变化就立刻发出统一提醒。

推荐的沟通方式 ​

如果 PR 还没有排到处理顺序,可以直接说明:

这个 PR 已经排进队列,目前不需要 rebase。等它进入评审/合并阶段后,我会通知你同步目标分支。

如果现在确实需要作者操作,应同时说明触发条件:

这个 PR 现在进入评审顺序了,目标分支已经合并了相关改动。请基于最新目标分支 rebase,解决冲突后重新运行检查。

核心原则是:发现技术问题,不等于立即要求别人行动;先确认时机、顺序和提出要求的权限。

这条规则来自一次真实的开源协作纠偏,完整经过见PR 有冲突,也不代表现在就要处理。

文档风格 ​

  • 标题直接说主题。
  • 段落短一点。
  • 命令必须可复制。
  • 风险和前提要写清楚。
  • 写清真实失败、判断依据和修正过程,不用成功学句子收尾。

从 Demo 到商用:用 AI 编程,把 Demo 做成能收钱、能长期运行的项目。