文档审阅流程

Istio 文档工作组(Docs WG)的维护者和工作组负责人审批针对 Istio 网站的所有更改。

文档审阅者 是一个受信任的贡献者,负责批准符合审阅标准的内容。 所有审阅都遵循 PR 内容审阅中描述的流程。

只有文档维护者和工作组负责人才能将内容合并到 istio.io 存储库

与 Istio 相关的内容通常需要在短时间内完成审阅,并非所有内容都具有同样的相关性。 鉴于投稿的时效性和有限的审阅者数量,我们必须确定内容审阅的优先级,以便大规模运作。 该页面提供了明确的审阅标准,以确保所有审阅工作一致可靠且遵循相同的质量标准

PR 内容审阅

文档审阅者、维护者和工作组负责人,对 PR 内容的审阅必须遵循审阅流程,以确保所有审阅一致。流程如下:

  1. 贡献者提交新的 PR 到 istio.io 仓库。
  2. 审阅者进行内容审阅,并确定它是否符合绝对验收标准
  3. 如果贡献者尚未加入任何与贡献内相关的技术工作组,则审阅者可将其加入到相应工作组。
  4. 贡献者审阅者协同工作,直到内容符合所有绝对验收标准,且 Issue 得到完全解决。
  5. 如果内容非常紧急,且满足补充验收标准需要大量工作,审阅者 可在 istio.io 仓库提交跟进 Issue,以在后续处理这些问题。
  6. 贡献者根据审阅者和贡献者的意见,处理所有反馈。跟进 Issue 中提到的问题将在后续解决。
  7. 技术工作组负责人或维护者批准 PR 内容,审阅者 可以批准 PR。
  8. 如果 Docs WG 维护者或负责人审阅了内容,则他们不仅会批准内容,还会对其进行合并。否则,维护者和负责人将自动收到审阅者的批准通知,并优先批准和合并已审阅的内容。

下图描述了该流程:

文档审阅流程

  • 贡献者 执行步骤在灰色节点。
  • 审阅者 执行步骤在蓝色节点。
  • 文档维护者和工作组负责人 执行步骤在绿色节点。

跟进 Issue

审阅者PR 内容审阅中提出跟进 Issue 时,需在 Issue 中包含以下信息:

  • 关于内容不符合补充接受标准的详细信息。
  • 指向原始 PR 的链接。
  • 技术主题专家(SMEs)用户名。
  • 添加 Labels 以便于问题排序。
  • 工作量估计:审阅者提供与原始贡献者一起解决剩余问题所需的最佳估计时间。

审阅标准

审阅流程,通过将明确的审阅标准应用于所有内容以支持我们的行为准则

绝对验收标准

  • 技术准确性:至少一名技术工作组负责人或维护者对内容进行审核和批准。
  • 正确的编码:必须通过所有的 lint 检查和测试。
  • 语言:内容必须清晰易懂。要了解更多信息,请参阅 Google 开发者风格指南的 highlightsgeneral principles
  • 链接和导航:内容中涉及的所有链接必须有效,且网站可以正常构建。

补充验收标准

  • 内容结构:良好的信息结构可增强阅读体验。
  • 一致性:内容遵循 Istio 贡献指南中的所有建议。
  • 风格:内容遵循 Google 开发者风格指南
  • 图形附件:遵循 Istio 图形创建指南
  • 示例代码:提供与内容密切相关且可测试的有效代码示例。
  • 内容服用:任何可重复的内容都遵循使用样板文本的可重用性策略。
  • 术语:所有新的术语都已经添加到术语表中,且定义清晰。