管理发布说明

本文档描述了 Oslo 库的发布说明的管理策略和位置。

问题描述

Oslo 库有几个潜在的受众

  • OpenStack 服务开发者

  • OpenStack 部署者

  • 其他开发者

这些受众希望在发布说明中获取的信息类型可能大相径庭。本策略描述了我们如何管理发布说明，以确保我们能够与每个受众进行适当的沟通。

拟议政策

针对开发者（无论是否属于 OpenStack 社区）的发布说明，都将处理在为库发布的开发者文档中。这确保了所有面向开发者的信息都集中在一个地方。

打包库 pbr 包含一个根据被打包项目的 git 历史自动生成 ChangeLog 文件的功能。该文件是 reStructuredText 格式，应直接包含在由 Sphinx 编译成 HTML 并发布在 https://docs.openstack.org/developer/ 下的开发者文档中，通过添加一个使用 include 指令加载生成文件的静态 history.rst 文件来实现。

可以向开发者文档直接添加其他开发者信息。代码中的文档字符串应使用 versionadded 指令为新功能或参数添加版本信息，并使用 warning 指令为弃用添加警告信息。

部署者的发布说明应通过 reno 进行管理，并发布在 https://docs.openstack.org/releasenotes/ 下。任何具有配置选项或其他面向部署者接口的库都应设置 reno 以发布发布说明。并非所有 Oslo 库都需要这样做。

面向部署者的发布说明应以他们为对象编写，并且仅描述从不阅读库源代码的人的角度来看的功能或更改。例如，如果更改对部署者不可见，则无需记录库的更改。配置选项或文件格式的更改应具有 reno 注释。内部 API 的更改不需要。新功能和错误修复应使用 reno 发布说明进行记录。例如，消息传递或数据库服务中更好的超时处理或重新连接管理等更改应具有 reno 发布说明。

替代方案与历史

过去我们专注于与使用 Oslo 库的开发者进行沟通。这已经不够了，因为我们现在管理配置选项和其他对使用 Oslo 库构建的软件的部署者可见的功能。

我们可以将部分内容添加到开发者文档中，但这会使构建 OpenStack 所有项目的单个发布说明集变得更加困难，或者至少链接到所有项目通用的发布说明位置。

实现

作者

主要作者：doug-hellmann

里程碑

本策略从 Mitaka 周期开始适用，当时我们将 reno 添加到了 oslo.log 和 oslo.config 中。

工作项

根据需要，为库添加 reno 构建指令和 CI 作业。

参考资料

修订历史

修订版

发布名称

描述

Mitaka

引入

注意

本作品采用知识共享署名 3.0 非移植许可协议授权。 http://creativecommons.org/licenses/by/3.0/legalcode