编写版本说明

报告问题 查看源代码

本文面向 Bazel 贡献者。

Bazel 中的提交说明包含一个 RELNOTES: 标记,后跟版本说明。Bazel 团队将用它来跟踪每个版本的更改并编写版本公告。

概览

  • 您的更改是 bug 修复吗?在这种情况下,您不需要版本说明。请附上对 GitHub 问题的引用。

  • 如果变更以用户可见的方式添加 / 移除 / 更改 Bazel,那么提及它可能会有所帮助。

如果发生了重大变更,请先遵循设计文档政策

指南

版本说明将由我们的用户阅读,因此应简短(理想情况下请用一句话),避免使用行话(Bazel 内部术语),应专注于变更内容。

  • 请附上相关文档的链接。几乎所有的版本说明都应包含链接如果说明中提及了标志、功能、命令名称,用户可能需要详细了解该标志。

  • 对代码、符号、标志或任何包含下划线的字词使用反引号。

  • 不要只是复制和粘贴 bug 描述。它们通常很隐秘,对我们来说很有意义,并且会让用户头疼。版本说明旨在以用户能够理解的语言解释更改的内容以及原因。

  • 始终使用现在时且格式为“Bazel 现在支持 Y”或“X 现在支持 Z”。我们不希望版本说明听起来像 bug 条目。所有版本说明条目都应包含丰富的信息,并使用一致的样式和语言。

  • 如果某个功能已被弃用或被移除,请使用“X 已弃用”或“X 已移除”。不能是“已移除”或“已移除”。

  • 如果 Bazel 现在执行了不同的操作,请使用现在时使用“X 现在 $newBehavior,而不是 $oldBehavior”。这样,用户就可以详细信息,了解使用新版本时会发生什么。

  • 如果 Bazel 现在支持或不再支持某项内容,请使用“Bazel 现在支持/不再支持 X”。

  • 说明移除 / 弃用 / 更改内容的原因。只需一句话就足够了,但我们希望用户能够评估对构建的影响。

  • 不要对未来的功能做出任何承诺。请避免使用“此标志将被移除”或“此操作会更改”。这会带来不确定性。用户会最先想到的是“何时?”,我们不希望用户开始担心他们当前构建的一些未知时间发生了中断。

处理

发布流程中,我们会收集每次提交的 RELNOTES 标记。我们会复制 Google 文档中的所有内容, 在这里我们可以查看、修改和整理笔记。

版本管理器向 bazel-dev 邮寄名单发送电子邮件。我们邀请 Bazel 贡献者参与到文档中,以确保他们的更改正确体现在公告中。

之后,系统会使用 bazel-blog 代码库将通知提交到 Bazel 博客