API 兼容性政策#

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

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

版本控制与向后兼容性#

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

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

任何API都可能在某些次要更新中被*弃用*。在这种情况下，弃用说明会添加到API文档中，并且API实现会进行修改以触发弃用警告（如果可能）。应该有另一种方法来重新实现之前使用已弃用API编写的相同功能。

任何API都可能被标记为 未来将被废弃 。在这种情况下，废弃计划会在文档中说明，并标明计划废弃该API的主要版本号，同时API的实现会被修改以触发一个未来警告（如果可能）。

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

因此，在首次弃用之后，任何API的删除至少需要两个次要版本。

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

实际的更改应按以下步骤进行：

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

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

鼓励开发人员为实现细节的对象使用明显的名称。例如，文档化API之外的属性应在名称前缀中包含一个或多个下划线。

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

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

修订更新可能还包含对未定义行为的更改。典型的例子是修复错误。另一个例子是实现的改进，这可能会改变文档中未显示的内部对象结构。因此，即使修订更新也不支持pickle的兼容性，除非pickled对象的完整布局在文档中明确说明。

兼容性基本上是根据文档来确定的，尽管它有时包含错误。假设文档总是比实现更强可能会使API变得混乱。因此，我们可能会在任何可能破坏与文档相关的兼容性的更新中修复文档错误。

备注

开发人员在修订更新中绝不能将同一功能的文档和实现同时作为“错误修复”进行修复。这种更改完全破坏了向后兼容性。如果您想同时修复这两方面的错误，请首先修复文档以使其符合实现，然后启动上述API更改程序。

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

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

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

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

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

任何导致现有环境必须修改的依赖库变更，都必须在主要更新中进行。此类变更包括以下情况：
- 放弃对依赖库的某些版本的支持（例如，放弃对 cuDNN v2 的支持）
- 添加新的强制依赖项（例如，将 h5py 添加到 setup_requires）
支持可选的包/库可以在小版本更新中完成（例如，在可选功能中支持 h5py）。

备注

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