如果您打算添加、更改或移除面向用户的功能, 重大架构更改时,您必须编写 并在提交更改前先对其进行审核。
以下是一些重大变更示例:
- 添加或删除原生 build 规则
- 对原生规则的破坏性更改
- 更改了原生构建规则语义,会影响更多 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 后,审核人员可以在代码审核期间提供初步意见。例如,主审核员可以建议添加其他审核员,或指出缺少的信息。审核主管会在批准 PR 时 认为可以开始审核流程。这并不意味着提案是完美无缺的 或将被批准;则意味着提案包含的信息足以 发起讨论。
公布新提案
提交 PR 后,向 bazel-dev 发送通知。
您可以复制其他群组(例如 bazel-discuss,以便从 Bazel 最终用户那里获取反馈)。
与审核者进行迭代
任何感兴趣的用户都可以对您的提案发表评论。尝试回答问题、阐明提案并解决疑虑。
讨论应在通知会话中进行。如果提案属于 Google 文档,可以改用评论(请注意,匿名评论是 )。
更新状态
当迭代处于以下状态时,创建一个新的 PR 以更新提案的状态 。将 PR 发送给同一审核人员并抄送给其他审核人员。
如需正式接受提案,主审核员需要确保其他审核员同意此决定,然后批准 PR。
从首次通知到获得批准之间必须至少相隔一周 提案。这可以确保用户有足够的时间阅读文档并 提出自己的疑虑。
在提案获得批准之前,您可以先开始实施,例如作为概念验证或实验。但是,您无法提交更改 。
选择审核员
主评价员应是具有以下特征的领域专家:
- 了解相关子系统
- 客观且能够提供建设性反馈
- 在整个审核期内可用,负责引导审核流程
不妨查看各种团队标签的联系人。
Markdown 与 Google 文档
您可以决定最适合您的方式,因为两者都可以。
使用 Google 文档的优势:
- 非常适合头脑风暴,因为上手非常简单。
- 协作编辑。
- 快速迭代。
- 轻松提出修改建议。
使用 Markdown 文件的好处:
- 用于链接的简洁网址。
- 修订版本的明确记录。
- 在公开链接之前,请务必设置访问权限。
- 可通过搜索引擎轻松搜索。
- 面向未来:纯文本不受任何特定工具的约束,也不需要连接到互联网。
- 即使作者已不在,您也可以更新这些内容。
- 它们可以自动处理(更新/检测无效链接、提取 作者名单等)。
您可以先在 Google 文档中进行迭代,然后再将其转换为 Markdown 以供日后参考。
使用 Google 文档
为保持一致性,请使用 Bazel 设计文档模板。 它包含必要的标题和可创建视觉元素 与 Bazel 的其他相关文档保持一致为此,请依次点击文件 > 复制,或点击此链接复制设计文档模板。
如需向所有人开放文档的访问权限,请依次点击共享 > 高级 > 更改…,然后选择“开启 - 知道链接的任何人”。如果您允许对文档添加评论,任何人都可以匿名评论,即使没有 Google 账号也可以。
使用 Markdown
文档存储在 GitHub 上,并使用 GitHub 风格的 Markdown(规范)。
创建一个 PR 以更新现有文档。重大更改应由文档审核员审核。任何人都可以批准琐碎的更改(例如拼写错误、格式错误)。
审核者工作流程
审核者负责评论和审核设计文档。
审核人员的一般责任
您负责审核设计文档, 并根据需要提供信息,并对通过审核流程的设计进行审批。
收到新提案时
- 快速浏览一下该文档。
- 如果缺少关键信息或设计不合适,请发表评论 项目目标。
- 推荐其他审核者。
- 在 PR 可以审核时予以批准。
审核流程
- 与设计作者讨论有问题的问题 或需要进一步说明
- 在适当情况下,邀请应该了解该设计的非审核人员提供反馈。
- 决定哪些评论必须由作者进行处理 审批。
- 如果您对提案的当前状态满意,请在讨论会话中写入“LGTM”(Looks Good To Me,即“看起来不错”)。
请针对所有设计审核请求遵循此流程。不批准设计 影响到 Bazel 的 设计索引。
主审核员的责任
您需自行负责做出有关实施的决定 一个待定设计如果您无法执行此操作,则应指定合适的代理(将 PR 重新分配给代理),或将 bug 重新分配给 Bazel 管理员以供进一步处理。
审核流程
- 确保评论和设计迭代流程能够继续进行 。
- 在获批之前,请确保已针对其他审核人员提出的问题 已解决。
获得所有审核者的批准后
- 请确保在邮寄名单中发布通知后至少已过 1 周。
- 确保 PR 更新了状态。
- 批准提案作者发送的 PR。
拒绝设计
- 确保 PR 作者发送 PR;或者向他们发送 PR。
- PR 会更新文档的状态。
- 向文档添加注释,说明设计无法在 其当前状态,并概述后续步骤(例如,“重新访问无效 假设并重新提交”)。