编写版本说明

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

本文档面向 Bazel 贡献者。

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

概览

  • 您的更改是否能够修复 bug?在这种情况下,您不需要发布版本说明。请 提供对 GitHub 问题的引用。

  • 如果更改以用户可见的方式添加 / 删除 / 更改 Bazel,则 可能更有好处

如果变更重大,请按照设计文档 政策

指南

版本说明将由我们的用户阅读,因此应简短(最好只使用一个 句子),避免使用专业术语(Bazel 内部术语),应重点关注 。

  • 添加指向相关文档的链接。几乎所有版本说明都应该 包含链接。如果说明中提到了标志、功能、命令名称 用户可能希望了解更多相关内容

  • 在代码、符号、标志或包含 下划线。

  • 不要只是复制和粘贴错误描述。它们通常比较神秘 会让用户感到困惑。版本说明为 以用户能理解的语言说明更改内容以及更改原因。

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

  • 如果某些资源已被弃用或移除,请使用“X 已弃用”或“X” 已被删除。”不“已移除”即“已删除”

  • 如果 Bazel 现在采取了不同的做法,请使用“X now $newBehavior”,而不是 $oldBehavior这样用户就能详细地了解 使用新版本。

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

  • 说明移除 / 弃用 / 更改的原因。有一句话是 但我们希望用户能够评估对构建的影响。

  • 请勿对未来推出的功能做出任何承诺。应避免“此标记将 已删除”或“这将改变”这会带来不确定性。首先 用户会想知道是“何时”?我们不希望孩子开始担心 他们目前的作品在某个未知的时间出现了故障。

流程

作为发行版的一部分 过程, 我们会收集每次提交的 RELNOTES 标记。我们会将所有内容复制到 Google 文档 您可以在其中查看、修改和整理笔记

发布管理员会向 bazel-dev 邮寄名单中的成员。 我们邀请了 Bazel 贡献者为文档提供内容, 他们的更改会正确反映在通知中。

之后,该通知会提交到Bazel 博客,使用 bazel-blog 存储库