API 兼容性策略#

本文档阐述了 CuPy API 兼容性的设计策略。开发团队在决定添加、扩展和更改 API 及其行为时应遵守本策略。

本文档是为用户和开发者编写的。用户可以根据本文档决定其代码对 CuPy 实现的依赖程度。开发者在创建包含接口更改的拉取请求之前应仔细阅读本文档。请注意，本文档在支持的兼容性级别上可能存在模糊之处。

版本控制与向后兼容性#

CuPy 的更新分为三个级别：主版本、次版本和修订版本。这些类型具有不同的向后兼容性级别。

  • 主版本更新包含破坏向后兼容性的颠覆性更改。

  • 次版本更新包含对 API 的添加和扩展，这些更改保持向后兼容性。

  • 修订版本更新包含对 API 实现的改进，但不更改任何 API 规范。

请注意，我们不支持完全的向后兼容性，这对于基于 Python 的 API 来说几乎是不可行的，因为无法完全隐藏实现细节。

破坏向后兼容性的流程#

弃用、移除及其准备工作#

任何 API 都可能在某些次版本更新中被弃用。在这种情况下，API 文档中会添加弃用说明，并且 API 实现会更改为触发弃用警告（如果可能）。应该有其他方法可以重新实现以前使用弃用 API 编写的相同功能。

任何 API 都可能被标记为将来移除。在这种情况下，文档中会说明移除，并附上计划移除该 API 的主版本号，并且 API 实现会更改为触发未来警告（如果可能）。

实际的移除应通过以下步骤完成

  • 将 API 标记为弃用。此时，用户不应在其新的应用程序代码中使用弃用的 API。

  • 之后，将 API 标记为将来移除。这必须在与弃用不同的次版本更新中完成。

  • 在上述更新中宣布的主版本中，移除该 API。

因此，任何 API 在首次弃用后，至少需要两个次版本才能被移除。

API 变更及其准备工作#

任何 API 都可能被标记为将来变更，以进行不兼容向后兼容性的更改。在这种情况下，文档中会说明更改，并附上计划更改该 API 的版本号，并且 API 实现会更改为在某些用法上触发未来警告。

实际的变更应通过以下步骤完成

  • 宣布 API 将来会变更。此时，实际的变更版本号不必准确。

  • 宣布后，将 API 标记为将来变更，并附上计划变更的版本号。此时，用户不应在其新的应用程序代码中使用标记的 API。

  • 在上述更新中宣布的主版本更新中，变更该 API。

支持的向后兼容性#

本节定义了次版本更新必须保持的向后兼容性。

文档化接口#

CuPy 拥有官方 API 文档。许多应用程序可以基于文档化的特性编写。我们支持文档化特性的向后兼容性。换句话说，仅基于文档化特性的代码在次版本/修订版本更新后也能正确运行。

鼓励开发者对实现细节的对象使用明显的名称。例如，文档化 API 之外的属性名称前应带有一个或多个下划线。

未文档化的行为#

文档中未说明的 CuPy 实现行为是未定义的。未文档化的行为不保证在不同的次版本/修订版本之间保持稳定。

次版本更新可能包含对未文档化行为的更改。例如，假设在次版本更新中添加了 API X。在之前的版本中，尝试使用 X 会导致 AttributeError。这种行为在文档中没有说明，因此是未定义的。因此，在次版本中添加 API X 是允许的。

修订版本更新也可能包含对未定义行为的更改。典型的例子是 bug 修复。另一个例子是实现上的改进，这可能会更改文档中未显示的内部对象结构。因此，即使是修订版本更新也不支持 pickling 的兼容性，除非 pickling 对象的完整布局有清晰的文档说明。

文档错误#

兼容性基本上是根据文档确定的，尽管文档有时会包含错误。假设文档总是比实现更强可能会导致 API 令人困惑。因此，我们可以在任何可能打破文档相关兼容性的更新中修复文档错误。

注意

开发者在修订版本更新中**不得**同时修复同一功能的文档和实现，并将其标记为“bug 修复”。这种更改会完全破坏向后兼容性。如果您想同时修复两方面的 bug，首先修复文档使其与实现一致，然后按照上述 API 更改流程进行操作。

对象属性和特性#

对象属性和特性有时会在次版本更新中相互替换。这不会破坏用户代码，除非代码依赖于属性和特性的具体实现方式。

函数和方法#

方法可能会在次版本更新中被可调用属性替换，同时保持参数和返回值的兼容性。这不会破坏用户代码，除非代码依赖于方法和可调用属性的具体实现方式。

异常和警告#

引发异常的规范被视为标准向后兼容性的一部分。未来的版本中，对于文档允许的正确用法，除非 API 更改过程完成，否则不会引发异常。

另一方面，任何 API 都可能在任何次版本更新中添加警告。这意味着次版本更新不保持警告的向后兼容性。

安装兼容性#

安装过程是兼容性的另一个关注点。我们通过以下方式支持环境兼容性。

  • 任何强制修改现有环境的依赖库更改必须在主版本更新中完成。此类更改包括以下情况：

    • 放弃支持的依赖库版本（例如，放弃 cuDNN v2）

    • 添加新的强制依赖项（例如，将 h5py 添加到 setup_requires）

  • 支持可选包/库可以在次版本更新中完成（例如，在可选功能中支持 h5py）。

注意

安装兼容性不保证 CuPy 的所有功能在支持的环境中都能正确运行。它可能包含仅在特定环境中出现的 bug。此类 bug 应在某些更新中修复。