弃用

OpenStack 项目应遵守此处概述的关于弃用功能和功能的指南。此过程旨在确保 OpenStack 的操作员和用户能够平稳地在版本之间升级，以及迁移到不再依赖随着时间推移而被移除的功能方面。必须小心避免破坏相邻版本之间的兼容性，以及在 发布节奏 中定义的 tick 版本之间的兼容性。

谨慎弃用的理由

给定服务的最终用户需要知道他们正在使用和依赖的功能或 API 是否仍然会得到软件的明日支持。给定服务的操作员和部署者希望能够异步地推出代码和配置更改，因此依赖于新代码与现有配置文件正确配合工作。

在开发的早期阶段，重要的是保持敏捷、进行实验并快速失败。在那个时候，承诺永远支持这些早期错误是不合理的。但是，随着项目的成熟和越来越多的用户依赖于现有功能，了解项目可以在未来删除功能、API 或更改配置选项的条件变得重要。这可能成为决定项目是否足够稳定和成熟以用于特定用例的因素。

指南

项目团队应遵循以下流程，以弃用对最终用户可见或对操作员可见的功能

1. 在代码中将功能、API 或配置选项标记为已弃用。将向最终用户、操作员或库用户发送适当的警告。代码将被冻结，并且仅接收最少的维护（仅为了使其继续按原样工作）。

2. 将为当前使用该功能的用户记录迁移路径。将在 openstack-discuss 上启动一个邮件线程，以确定有多少人正在使用已弃用的 API 或功能，以及实施迁移计划的成本。迁移路径可能是“停止使用该功能”：然后成本与使用该功能的人数以及他们对该功能的依赖程度密切相关。

3. 如果交付物是 Interop 工作组指南的一部分，项目将检查已弃用的功能是否是公开的功能的一部分。如果是，则过时日期（如下所示）还需要考虑 Interop WG 功能弃用计划。

4. 基于这些数据，将设置过时日期。至少，该功能（或 API 或配置选项）应在至少一个“tick”版本分支中标记为已弃用（并且仍然受支持），并且至少持续 12 个版本的发布。考虑以下示例

   1. 如果在 2023 tick 版本中弃用某个功能，则可以在 2023 tock 版本中将其删除。仅部署 tick 版本的操作员会收到一个通知，并在下一个 tick 版本之前有 12 个月的时间来删除该功能。部署 tick-tock 版本的操作员会收到一个通知，并在删除该功能的版本之前有 6 个月的时间，就像在 tick-tock 模型之前一样。

   2. 如果在 2023 tock 版本中弃用某个功能，它还必须存在于 2024 tick 版本中，并且必须明确标记为已弃用（以便仅部署 tick 版本的操作员收到该警告）。可以在 2024 tock 版本中删除该功能。仅部署 tick 版本的操作员会收到一个通知，并在下一个 tick 版本之前有 12 个月的时间来删除该功能（早已删除）。部署 tick-tock 的操作员会收到两个通知，并且仍然在删除该功能的版本之前有 12 个月的时间。

请注意，此延迟是必需的最低值。对于重要功能，建议已弃用的功能至少出现在接下来的两个 tick 版本分支中。理想情况下，功能仅在 tick 版本中弃用和删除，以使会计工作量最小化，但有时更灵活可能更有利。

另一个需要考虑的场景是在 tock 版本中引入的实验性功能，这些功能“无法存活”并且需要快速删除。在这种情况下，最早的可能序列是在下一个 tick 版本中弃用（有效地将该功能作为已弃用引入给仅部署 tick 的部署者），然后在下一个 tock 版本中删除。

此外，项目应

• 使用自动化测试来验证配置文件和数据库模式是否从版本到版本向前兼容，并且此策略不会意外中断（例如，一个闸门炸弹测试）。

• 使用自动化测试来验证上述兼容性也在tick版本之间保持稳定，以便操作员能够跳过 tock 版本。

• 现有的配置选项不会以会改变软件行为或以其他方式使现有的配置文件损坏的方式更改其含义。

注意：这些指南适用于服务和库功能弃用策略和程序。