选择版本号¶
作为推动从 oslo 孵化器中发布独立库的工作的一部分，我们进行了多次关于版本控制和发布计划的讨论。 这次尝试旨在收集我们在这些讨论中做出的所有决定，并阐述我们所采取方法的理由。
问题描述¶
我们有两种类型的 Oslo 库。 像 oslo.config 和 oslo.messaging 这样的库是通过提取孵化代码、更新公共 API 并进行打包而创建的。 像 cliff 和 taskflow 这样的库从一开始就作为独立软件包创建，后来被 Oslo 团队采用以管理它们的开发和维护。
孵化库在发布周期结束时发布，就像其他集成软件包一样。 采用的库在开发过程中“按需”发布。
oslo.config 的第一个版本是 1.1.0，作为 grizzly 版本的组成部分。 oslo.messaging 的第一个版本是 1.2.0，作为 havana 版本的组成部分。 oslo.config 在 havana 期间也更新到 1.2.0。 所有“采用”的库（在其他地方创建并引入 Oslo 项目的库）在撰写此策略的初稿时，版本号都低于 1.0.0。
拟议政策¶
在 Juno 会议上，Josh Harlow 提出 我们应该为 oslo 库使用语义版本控制 (SemVer)。 该提议还包括关于允许在某些发布边界处破坏向后兼容性的想法，而本策略尚未解决该问题。 第一步是选择一个合理的发布版本控制方案。
SemVer 被广泛使用，并为我们提供了关于选择新版本号的相对清晰的指导原则。 Oslo 从 Juno 周期开始，开始使用 pbr 修改后的 SemVer 进行新发布。
SemVer 生命周期¶
新库应从版本 0.1.0 开始，按照 SemVer 策略进行递增，直至周期结束，目标是在其第一个完整开发周期结束时达到 1.0.0。
现有库将遵循 SemVer，从 Kilo 开始时的版本开始递增。
频繁发布¶
虽然我们可以使用 Oslo 库的 master 分支运行 gate 作业，但开发人员必须采取额外的步骤才能以这种方式在本地运行单元测试。 为了减少此过程的开销，同时仍然确保开发人员使用最新版本的代码，我们在发布周期内相当频繁地发布库。 我们在 Oslo 团队会议期间每周进行一次检查，并在周一早上认为有必要时标记发布。 等到周一可以防止我们在周末开始前引入 gate 问题。
稳定分支的补丁发布¶
可以从稳定分支对现有库发布进行更新。 例如，签出 stable/icehouse 的 oslo.config 可以发布 1.3.1。 我们没有关于是否会创建补丁发布的正式策略，或者应用程序是否最好使用库的最新版本。
所有库都需要维护稳定分支以支持这些补丁发布。 我们将限制 Oslo 库在稳定分支中使用的版本，以允许补丁发布，但不允许进行次要版本号更改的更新。
替代方案与历史¶
与 OpenStack 的其余部分同步¶
Oslo 团队可以在任何时候发布库，而无需考虑 OpenStack 其余部分的发布计划。 我们必须为随时可能更新的我们不维护的库做好准备，因此这不会为我们的发布和测试流程增加新的方面。 然而，Oslo 是 OpenStack 的一部分，因此我们最初希望与相同的计划保持一致。
Mark McLoughlin 撰写了 一篇很好的理由，总结如下：“我的直觉是像任何其他核心项目一样做所有事情，除非在 Oslo 确实是一个特殊案例的情况下。” 通过遵循其他项目的发布计划，我们可以获得所有好处（将重点从功能转移到错误；稳定分支；与我们库的用户同步；OpenStack 发布管理器）。
当我们停止创建 Alpha 版本时，我们停止了完全的发布同步。 我们仍然在发布周期的结束时发布给定主要和次要版本号的最终版本，并且我们仍然遵循功能冻结流程。
Alpha 版本¶
过去，Oslo 库的 alpha 版本作为 tarball 分发到 openstack 服务器上，而官方版本则发布到 PyPI。 需要 alpha 版本的应用程序在他们的需求列表中指定 tarball，然后跟上版本说明符。 这使我们能够准备 alpha 版本，而无需担心它们的发布会通过使新的库版本可用于 pip 来破坏持续部署系统。 这种方法仍然使应用程序开发人员难以依赖 oslo 库的新功能，直到生成 alpha 版本为止。
当我们的 CI 系统中引入 PyPI 镜像时，依赖于不可用于镜像的 tarball 与我们希望 gate 系统仅从软件包镜像安装的愿望相冲突。 当我们开始仅从镜像安装时，我们需要以镜像可以使用的格式发布我们的 alpha 版本，因此我们开始在发布期间使用预测的最终版本的 alpha 版本号。
在 Kilo 会议上，一群 Oslo 库的消费者强烈要求我们停止使用 alpha 版本控制并切换到简单的 SemVer。 我们从 Kilo 开始这样做，结果好坏参半（破坏性更改进入了稳定分支测试环境）。 此时，回到 Kilo 期间的 alpha 版本没有意义，因此我们将坚持当前计划并解决由此产生的问题。
https://etherpad.openstack.org/p/kilo-oslo-alpha-versioning
我们决定新库应从版本 0.1.0 开始，按照 SemVer 策略进行递增，直至周期结束，目标是在那时达到 1.0.0。
现有库将遵循 SemVer，从 Kilo 开始时的版本开始递增。
Juno 策略¶
现有库 oslo.config 和 oslo.messaging 的版本将从它们的 Icehouse 版本开始递增，但在 Juno 周期结束时更新次要编号 (1.x.0)。
所有使用小于 1.0 的数字的采用库都将在 Juno 周期结束时作为 1.0.0 发布，理由是我们预计部署者将在生产中使用它们。
在 Juno 期间毕业的新库发布将标记为常规发布号 < 1.0。 这使我们能够将它们添加到我们的需求列表中（它不会接受没有其他发布的软件包的 alpha 版本）。 在 Juno 结束时，我们将标记这些库为 1.0.0。
Juno 期间的现有库发布都应标记为预期基于 SemVer 的发布号的 alpha 版本 (1.0.0.0aN 或 1.2.0.0aN 或其他)。 新的 CI 系统可以创建 Python wheel 包并将其发布到适当的服务器，这意味着项目将不再需要显式引用预发布 tarball。 除非您使用命令行标志显式请求安装任何可用的 alpha 版本，或者显式要求 alpha 版本，否则 pip 不会安装 alpha 库。 pip <= 1.3 不支持控制 alpha 的标志（它们始终被看到并安装），但也不支持 wheel，因此我们仅将 alpha 发布为 wheel 以确保旧的 pip 不会看到它们。
Gate 中的跨项目单元测试¶
我们为 Juno 制定了一个蓝图，用于 为应用程序和 oslo 库添加跨项目单元测试 gate。 这将使我们能够验证应用程序的测试不会在 Oslo 库更改时中断，并且这些测试不会对 Oslo 库的实现细节做出假设。 然而，这种级别的测试被认为在测试服务器方面成本太高，因此该计划被放弃了。
稳定分支中的需求上限¶
我们通常不使用 Oslo 库的需求规范的上限，因此新发布可能会自动被构建 OpenStack 应用程序稳定分支的持续部署系统采用。 虽然我们过去一直小心地保持 API 兼容性，但新的发布可能会破坏较旧的应用程序。 应用程序可以使用 SemVer 编号添加上限，但这样做可能会阻止它们看到错误修复，因此不建议这样做。
在 Kilo 会议期间，我们讨论了对稳定分支中的版本进行上限。 会议后立即尝试这样做失败了，因为它阻止了一些升级正常工作。 应用上限的工作正在进行中，超出本策略的范围。
在库中标记里程碑¶
我们不会像在应用程序中那样在里程碑处标记库，因为我们用于里程碑的标签（例如，2014.2.b1）不是库的有效版本，并且会与其他发布顺序混乱。 我们可能会在里程碑左右的时间标记一个 alpha 版本，但由于我们无论如何都是按需进行这些操作，因此没有严格的规则规定我们必须在该时间进行操作。
实现¶
里程碑¶
当前策略适用于 Kilo。
工作项¶
N/A
参考资料¶
修订历史¶
发布名称 |
描述 |
|---|---|
Juno |
引入 |
注意
本作品采用知识共享署名 3.0 非移植许可协议授权。 http://creativecommons.org/licenses/by/3.0/legalcode
