如果您打算添加、更改或移除面向用户的功能,或者对 Bazel 进行重大架构更改,则必须撰写设计文档并接受审核,然后才能提交更改。
下面列举了一些重大变更:
- 添加或删除原生构建规则
- 原生规则的重大更改
- 对原生构建规则语义的更改,这些更改会影响多个规则的行为
- 对 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-think),以获取 Bazel 最终用户的反馈。
与审核人员进行迭代更新
任何感兴趣的人都可以对您的提案发表评论。试着回答问题、阐明提案并解决问题。
讨论应该在公告会话中进行。如果提案位于 Google 文档中,则可改用注释(请注意,允许匿名评论)。
更新状态
创建新的 PR,以便在迭代完成后更新提案的状态。将 PR 发送给同一潜在客户评估人员,并抄送其他评估人员。
为了正式接受提案,潜在客户审核者在确保其他审核者同意决策后,会批准 PR。
从第一个公告到提案获得批准之间必须至少相隔 1 周。这样可确保用户有足够的时间阅读文档并分享他们的顾虑。
可以在提案被接受之前开始实现,例如作为概念验证或实验。但是,在审核完成之前,您无法提交更改。
选择潜在客户评估人员
审核潜在客户应是符合以下条件的领域专家:
- 了解相关子系统
- 有目标且能够提供建设性反馈
- 在整个审核期内都可用,以主导流程
建议检查联系人的各种团队标签。
Markdown 与 Google 文档
确定最适合您的方式,因为两者都接受。
使用 Google 文档的好处:
- 易于上手,因此非常适合集思广益。
- 协作编辑。
- 快速迭代。
- 提出修改建议的简便方法。
使用 Markdown 文件的优势:
- 简洁网址用于链接。
- 明确的修订记录。
- 在公开链接之前,请记得设置访问权限。
- 方便搜索引擎进行搜索。
- 可适应未来变化:纯文本不能受任何特定工具的约束,也不需要互联网连接。
- 即使作者已不在线,您也可以对其进行更新。
- 它们可以自动执行(更新/检测无效链接、提取作者列表等)。
您可以选择先对 Google 文档进行迭代,然后再将其转换为 Markdown 以供后代使用。
使用 Google 文档
为保持一致性,请使用 Bazel 设计文档模板。它包含必要的标头,并与其他 Bazel 相关文档在外观上保持一致。为此,请依次点击 File > Make a copy,或点击此链接为设计文档模板创建副本。
如需将您的文档设为可供所有人阅读,请依次点击 Share > Advanced > Change...,然后选择“On - Any with the link”(开启 - 知道链接的任何人)。如果您允许对文档发表评论,那么任何人都可以匿名评论,即使没有 Google 帐号也是如此。
使用 Markdown
文档存储在 GitHub 上,并使用 Markdown 的 GitHub 变种(规范)。
创建 PR 以更新现有文档。重大更改应由文档审核人员进行审核。任何人都可以批准细微的更改(例如拼写错误、格式设置)。
审核人员工作流程
审核者评论、审核并批准设计文档。
审核人员的一般职责
您负责审核设计文档,在需要时要求提供更多信息,并批准能够通过审核流程的设计。
当您收到新提案时
- 快速看一下文档。
- 如果关键信息缺失或设计不符合项目目标,请添加注释。
- 推荐其他审核者。
- 在 PR 可供审核时批准该 PR。
在审核过程中
- 就有问题或需要澄清的问题与设计作者进行对话。
- 如果合适的话,可以邀请应了解其设计的非审核者发表评论。
- 决定哪些评论必须先由作者处理,然后才能获得批准。
- 如果您对提案的当前状态感到满意,请在讨论会话中写下“LGTM”(看起来不错)。
对于所有设计审核请求,请遵循此流程。不批准影响 Bazel 的设计(如果这些设计未包含在设计索引中)。
负责人审核人员的职责
您要负责决定是否采用待处理设计。如果您无法执行此操作,则应确定合适的受托人(将 PR 重新分配给受托人),或者将 bug 重新分配给 Bazel 管理器,以供进一步处理。
在审核过程中
- 确保评论和设计迭代过程有建设性地向前推进。
- 在批准之前,确保其他审核者提出的问题已解决。
获得所有审核者批准后
- 确保自通知在邮寄名单上发布后至少已有 1 周。
- 确保 PR 更新了状态。
- 批准提案创建者发送的 PR。
拒绝设计
- 确保 PR 作者发送 PR;或发送 PR。
- PR 会更新文档的状态。
- 在文档中添加注释,说明当前设计无法获得批准的原因,并概述后续步骤(例如“重新审视无效的假设并重新提交”)。