PDEP-17: 向后兼容性和弃用策略

摘要

本 PDEP 定义了 pandas 的向后兼容性和弃用策略。

对 pandas 当前版本策略 的主要补充包括：- 弃用的功能应在至少两个次要版本中保持不变，然后才能进行更改或移除。- 弃用应最初使用 `DeprecationWarning`，然后在计划移除它们的主要版本之前的最后一个次要版本中切换到 `FutureWarning`，以获得更广泛的可见性。

动机

拥有清晰的向后兼容性和弃用策略对于构建健康的生态系统至关重要。我们希望确保用户可以依赖 pandas 的稳定性，同时仍然允许库不断发展。

本策略将确保用户有足够的时间处理弃用，同时最大限度地减少对下游包用户的影响。

范围

本 PDEP 涵盖了 pandas 处理向后兼容性以及弃用和移除过程的方法。

背景

pandas 使用语义化版本控制的一种宽松变体。
pandas 版本号采用 `MAJOR.MINOR.PATCH` 的格式。

通用策略

本策略适用于 公共 API。任何不属于 公共 API 或被标记为“实验性”的内容，可能随时更改或移除。

某些错误修复可能需要破坏向后兼容性。在这种情况下，不需要弃用周期。然而，对用户影响较大的错误修复可能会被视为破坏性更改。一个更改是错误修复还是 API 破坏性更改是一个判断问题。

弃用过程

弃用提供了一种警告开发者并给予他们时间调整代码以适应新功能的方式，以免旧行为最终被移除。

弃用警告消息应：- 提供有关正在更改内容的信息。- 如果有替代方案，提及如何实现类似的行为。- 对于大规模弃用，建议包含弃用的原因，并附上讨论链接以获取用户反馈。

此外，当引入弃用时，应：- 使用适当的警告类。更多信息可在下方找到。- 在警告行上方添加 GitHub 问题/PR 号码作为注释。- 在发行说明中添加一个条目。- 在文档中使用 `.. deprecated::` 指令提及该功能已被弃用。

使用哪种警告类

弃用应最初使用 `DeprecationWarning`，然后在计划移除它们的主要版本之前的最后一个次要版本中切换到 `FutureWarning`，以获得更广泛的可见性。
通过使用适当的 `PandasDeprecationWarning` 变量，可以忽略此实现细节，该变量将根据 pandas 版本被别名为适当的警告类。

强制执行弃用

当强制执行弃用时，应：- 在发行说明中添加一个条目。- 对于 API 更改，将文档中的 `.. deprecated::` 指令替换为 `.. versionchanged::` 指令。

PDEP-17 历史