设计文档

如果您打算添加、更改或移除面向用户的功能,或者对 Bazel 进行重大架构更改,则必须编写设计 101}文档,并接受审核,然后再提交更改。

以下是一些重大更改的示例:

  • 添加或删除原生构建规则
  • 原生规则的重要更改
  • 原生构建规则语义的变化会影响多条规则的行为
  • 对 Bazel 的规则定义 API 的更改
  • Bazel 用于连接到其他系统的 API 的变化
  • 对 Starlark 语言、语义或 API 的更改
  • 可能对 Bazel 性能或内存用量产生广泛影响的更改(效果好坏)
  • 广泛使用的内部 API 的变化
  • 对标志和命令行界面的更改。

设计审核的原因

在编写设计文档时,您可以与其他 Bazel 开发者协调,并从 Bazel 的核心团队寻求指导。例如,当提案添加、移除或修改 BUILD、WORKSPACE 或 bzl 文件中提供的任何函数或对象时,请将 Starlark 团队添加为审核者。 设计文档在提交之前要接受审核,原因如下:

  • Bazel 是一个非常复杂的系统;看起来很细微的本地更改 - 可能会产生重大的全球后果。
  • 该团队会收到用户的多项功能请求;此类请求的评估不仅需要考虑技术可行性,而且需要重视与其他功能请求有关。
  • Bazel 功能经常由核心团队以外的人实现;此类 Bazel 贡献者差别很大。
  • Bazel 团队本身的专业水平各不相同;没有任何团队成员完全了解 Bazel 的各个方面。
  • 对 Bazel 的更改必须考虑向后兼容性,并避免破坏性更改。

Bazel 的设计审核政策有助于最大限度地提高可能性:

  • 所有功能请求均须获得基准级别审查。
  • 合适的人员会在设计可能不起作用的实现方法之前权衡设计。

要开始帮助,请先查看 Bazel 提案代码库中的设计文档。设计工作还在进行中,因此实施细节会随着时间而变化并产生反馈。已发布的设计文档会捕获初始设计,不会在设计实施时进行持续更改。有关当前 Bazel 功能的说明,请务必参阅相关文档。

贡献者工作流程

作为贡献者,您可以编写设计文档、发送拉取请求以及为您的提案请求审核人员。

编写设计文档

所有设计文档都必须有一个标题,其中包括:

  • 作者
  • 上次重大更改的日期
  • 审核者列表,包括一位(且仅一名)负责人审核者
  • 当前状态(草稿、审核中、已批准、已拒绝、正在实施) 1},已实施
  • 指向讨论帖的链接(将在通知后添加

该文档可编写为可在全球范围内阅读的 Google 文档,也可以使用 Markdown 编写。阅读下文,了解 Markdown / Google 文档对比

对用户可见的影响必须有记录对向后兼容性的影响的部分(必要时包含发布计划)。

创建拉取请求

通过创建拉取请求 (PR) 将设计文档添加到设计索引,共享您的设计文档。将您的 Markdown 文件或文档链接添加到 PR。

尽可能选择首席审核人员,并抄送其他审核人员。如果您没有选择首席审核人员,那么 Bazel 维护人员会为您的公关人员分配一份。

创建 PR 后,审核人员可以在代码审核期间做出初步评论。例如,首席审核人员可以建议额外的审核人员,或指出缺少信息。当认为审核人员可以开始执行公关流程时,审核人员会批准公关流程。这并不意味着提案是完美的,也不会获得批准;则表示提案包含足够的信息,能够开始讨论。

发布新提案

提交 PR 时,向 Bazel-dev 发送通知。

您可以复制其他群组(例如 Bazel-discuss),以便获取 Bazel 最终用户的反馈。

与审核者进行迭代

任何相关人员都可以对您的提案发表评论。尝试回答问题,阐明提案并解决问题。

应在讨论会话中进行讨论。如果提案位于 Google 文档中,则可改用注释(请注意,允许匿名注释)。

更新状态

在迭代完成后,创建新的 PR 以更新提案的状态。将 PR 发送给同一位审核员,然后抄送其他审核员。

为了正式接受提案,首席审核人员会确保公关团队确认其他审核人员同意相关决定。

首次公告和批准提案之间必须至少间隔 1 周。这样可以确保用户有足够的时间阅读文档并表达他们的想法。

可以在提案被接受前开始实施,例如作为概念验证或实验。但是,在审核完成之前,您无法提交更改。

选择首席评价者

首席审核人员应该是符合以下条件的网域专家:

  • 了解相关子系统
  • 客观,能够提供有建设性的反馈
  • 在整个审核期内,可用于主导此流程

建议检查联系人的各种团队标签

Markdown 与 Google 文档

请确定最适合您的选项,因为两者都会被接受。

使用 Google 文档的好处:

  • 这对于讨论会比较有效,因为很容易上手。
  • 协作编辑。
  • 快速迭代。
  • 轻松提出修改建议。

使用 Markdown 文件的优势:

  • 清除链接网址。
  • 明确的修订版本记录。
  • 在公开链接之前,别忘了设置访问权限。
  • 通过搜索引擎轻松进行搜索。
  • 面向未来:纯文本不受任何特定工具的约束,不需要互联网连接。
  • 即使作者不再在身边,也可以进行更新。
  • 系统可以自动对其进行处理(更新/检测无效链接、提取作者列表等)。

您可以选择先迭代 Google 文档,然后再将其转换为 Markdown 以备后用。

使用 Google 文档

为保持一致,请使用 Bazel 设计文档模板。 它包含必要的标头,并在外观上与其他 Bazel 相关文档保持一致。为此,请依次点击 File > Make a copy,或者点击此链接以复制设计文档模板

要让所有人读取您的文档,请依次点击共享 > 高级 > 更改...,然后选择“开启 -知道链接的任何人”。 如果您允许对文档发表评论,则任何人都可以匿名评论,即使没有 Google 帐号也无妨。

使用 Markdown

文档存储在 GitHub 上并使用 Markdown 的 GitHub 变种规范)。

创建 PR 以更新现有文档。如果有较大变化,应由文档审核者进行审核。细微更改(例如拼写错误、格式设置)都可以得到任何人的批准。

审核者工作流程

审核者可以评论、审核和批准设计文档。

审核员的一般责任

您负责审核设计文档,根据需要索取更多信息,并批准通过审核流程的设计。

收到新提案后

  1. 请快速查看此文档。
  2. 注释缺少关键信息或者设计与项目目标不符。
  3. 建议其他审核人员。
  4. 在准备审核时批准 PR。

在审核期间

  1. 与设计作者就有问题或需要说明的问题进行对话。
  2. 在适当情况下,邀请可能不了解审核者的评论,让他们了解相应设计。
  3. 确定作者必须发表哪些评论作为先决条件。
  4. 对提案的当前状态感到满意时,请在讨论会话中撰写“LGTM”(看起来不错)。

对于所有设计审核请求,都请遵循此流程。如果影响 Bazel 的设计不在 Design index 中,请勿批准。

审核人员的职责

您有责任决定是否实施待处理的设计。如果您无法执行此操作,则应确定合适的受托人(将 PR 重新分配给受托人),或者将错误重新分配给 Bazel 管理器以供进一步处理。

在审核期间

  1. 确保评论和设计迭代过程具有建设性。
  2. 在获得批准之前,请确保其他审核人员的问题已得到解决。

全部审核人批准后

  1. 确保自邮寄名单中的公告起已过去至少 1 周的时间。
  2. 确保 PR 更新状态。
  3. 批准提案作者发送的 PR。

拒绝设计

  1. 确保 PR 作者发送 PR;或向其发送 PR。
  2. PR 会更新文档状态。
  3. 在文档中添加注释,说明设计无法以当前状态获得批准的原因,并概述后续步骤(如果有),例如“重访无效假设并重新提交”。