设计文档

<ph type="x-smartling-placeholder"></ph> 报告问题 查看来源 敬上 每晚 · 7.3。 · 7.2。 · 7.1。 · 7.0。 · 6.5

如果您打算添加、更改或移除面向用户的功能, 重大架构更改时,您必须编写 并在提交更改前先对其进行审核。

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

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

进行设计审核的原因

编写设计文档时,你可以与其他 Bazel 开发者协调 并向 Bazel 核心团队寻求指导。例如,当某个提案添加 移除或修改 BUILD、WORKSPACE 或 .bzl 文件,请将 Starlark 团队添加为审核者。 设计文档在提交之前需要接受审核,原因如下:

  • Bazel 是一个非常复杂的系统看似无害的本地更改 将造成严重的全球性后果。
  • 该团队会收到用户的很多功能请求;此类请求必须是 不仅评估了技术可行性,还评估了相关解决方案的重要性, 其他功能请求
  • Bazel 功能通常由核心团队以外的人员实施; 这些贡献者拥有不同水平的 Bazel 专业知识。
  • Bazel 团队本身的专业知识水平各不相同;没有任何团队成员 全面掌握了 Bazel 的各个方面。
  • 对 Bazel 的更改必须考虑向后兼容性并避免中断 更改。

Bazel 的设计审核政策有助于最大限度地提高出现以下情况的可能性:

  • 我们会对所有功能请求进行基本审查。
  • 合适的人会先权衡设计,然后再进行投资 可能无法正常运行的实施方式。

为了帮助您快速上手,请参阅 Bazel 提案代码库。 设计仍在进行中,因此实现细节可能会随时间而变化 并提供反馈。已发布的设计文档记录了初始设计、 而不是在设计实施过程中正在进行的更改。请务必前往 当前 Bazel 功能的说明文档。

捐助者计划工作流程

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

编写设计文档

所有设计文档的标题都必须包含以下内容:

  • 作者
  • 上次重大变更的日期
  • 评价者列表,包括一位(且只有一位) 潜在客户评估员
  • 当前状态(草稿、审核中、已批准已拒绝已实现已实现
  • 讨论帖的链接(在公告之后添加

该文档可以采用全局可读的 Google 文档使用 Markdown。请阅读以下内容,了解 Markdown 与 Google 文档比较

对用户可见的提案必须有一个部分记录 对向后兼容性的影响(并根据需要提供部署计划)。

创建拉取请求

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

如果可能,选择一名首席审核员。 并抄送给其他审核人。如果您不选择首席审核者,则 Bazel 维护人员将为您的公共关系分配一个。

您创建 PR 后,审核人员可以在 代码审核。例如,审核主管可以推荐额外的审核人员,或者 指出缺失的信息。审核主管会在批准 PR 时 认为可以开始审核流程。这并不意味着提案是完美无缺的 或将被批准;则意味着提案包含的信息足以 发起讨论。

公布新提案

发送通知给 bazel-dev(当 PR 已提交。

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

通过审核人员反复改进

任何感兴趣的人都可以对您的提案发表评论。尝试回答问题, 阐明提案并消除疑虑

讨论应在通知会话中进行。如果提案属于 Google 文档,可以改用评论(请注意,匿名评论是 )。

更新状态

当迭代处于以下状态时,创建一个新的 PR 以更新提案的状态 。将 PR 发送给同一审核人员并抄送给其他审核人员。

要正式接受提案,潜在客户审核人员应先批准 PR, 确保其他审核者认同相应决定。

从首次通知到获得批准之间必须至少间隔一周 提案。这可以确保用户有足够的时间阅读文档并 提出自己的疑虑。

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

选择审核员

审核主管应是具备下列条件的网域专家:

  • 了解相关子系统
  • 客观且能够提供建设性反馈
  • 在整个审核周期内提供,主导审核过程

考虑查看各个团队的联系人 标签

Markdown 与 Google 文档

您可以决定最适合您的方式,因为两者都可以。

使用 Google 文档的优势:

  • 很容易上手,因此很适合集思广益。
  • 协作编辑。
  • 快速迭代。
  • 轻松提出修改建议。

使用 Markdown 文件的优势:

  • 用于链接的简洁网址。
  • 修订版本的明确记录。
  • 在公开链接之前,别忘了设置访问权限。
  • 通过搜索引擎轻松搜索。
  • 满足未来需求:纯文本不会受到任何特定工具的束缚 且无需连接到互联网。
  • 即使作者不在您身边,也可以更新这些评论。
  • 它们可以自动处理(更新/检测无效链接、提取 作者名单等)。

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

使用 Google 文档

为保持一致性,请使用 Bazel 设计文档模板。 它包含必要的标题和可创建视觉元素 与 Bazel 的其他相关文档保持一致为此,请点击文件 > 复制,或点击此链接复制设计文档 模板

要让所有人都能阅读您的文档,请点击 分享 >高级 >更改...,以及 然后选择“开启 - 知道此链接的任何人”。如果您允许在文档中添加评论, 任何人都可以匿名发表评论,即使没有 Google 账号也无妨。

使用 Markdown

文档存储在 GitHub 上,并使用 GitHub 类型的 Markdown (规范)。

创建 PR 以更新现有文档。重大变更 由文档审核人员审核。细微更改(例如拼写错误、格式设置) 任何人都可以批准。

审核人员工作流程

审核者负责评论和审核设计文档。

审核人员的一般责任

您负责审核设计文档, 并根据需要提供信息,并对通过审核流程的设计进行审批。

收到新提案时

  1. 快速查看文档。
  2. 如果缺少关键信息或设计不合适,请发表评论 项目目标。
  3. 推荐其他审核者。
  4. 在 PR 可以审核时予以批准。

在审核过程中

  1. 与设计作者讨论有问题的问题 或需要进一步说明
  2. 在适当情况下,邀请非审核者提供评论,让他们了解应该了解什么情况 设计。
  3. 决定哪些评论必须由作者处理 审批。
  4. 输入“LGTM”(Looks Good To Me) 时,请在讨论会话中加入 对提案的当前状态感到满意

对于所有设计审核申请,请遵循此流程。不批准设计 影响到 Bazel 的 设计索引

审核负责人的职责

您需自行负责做出有关实施的决定 一个待定设计如果无法做到这一点 合适的受托人(将 PR 重新分配给该受托人),或将错误重新分配给 以便进行进一步处理

在审核过程中

  1. 确保评论和设计迭代流程能够继续进行 。
  2. 在审批之前,请确保已针对其他审核人员提出的问题 已解决。

获得所有审核者的批准后

  1. 请确保自公告 邮寄名单。
  2. 确保 PR 更新了状态。
  3. 批准提案作者发送的 PR。

拒绝设计

  1. 确保 PR 作者发送 PR;或者向他们发送公共关系
  2. PR 会更新文件的状态。
  3. 向文档添加注释,说明设计无法在 其当前状态,并概述后续步骤(例如,“重新访问无效 假设并重新提交”)。