API 生命周期和弃用策略¶
API 生命周期¶
每个 ExecuTorch API 都属于以下生命周期状态之一
实验性 (Experimental)
处于此阶段的 API 正在积极开发中,随时可能更改或删除。不过,除非从社区收集到足够的负面反馈或找到了更好的替代方案,否则我们期望最终将其提升为 稳定 (Stable) 版。
实验性 (Experimental) API 将被明确标记(参见下面的“如何标记 API 状态”部分)。
实验性 (Experimental) API 可能会在不通知的情况下更改或删除,开发者不应期望其具备稳定性保证。
稳定 (Stable)
未标记为 实验性 (Experimental) 或 已弃用 (Deprecated) 的 API 被视为 稳定 (Stable)。
处于此阶段的 API 已经过充分测试,被认为可用于生产环境。
推荐的最佳实践是不要弃用稳定的 API。在编写 API 时,应以一种未来无需弃用的方式编写。
稳定 (Stable) API 可以更改,但不能是破坏性更改。如果必须进行破坏性更改,稳定 (Stable) API 将始终先转换为 已弃用 (Deprecated) 状态,然后才能从库中移除/发生破坏性更改。
已弃用 (Deprecated)
处于此阶段的 API 不再推荐使用,并将在 ExecuTorch 的未来版本中移除。
已弃用 (Deprecated) API 将被明确标记(参见下面的“如何标记 API 状态”部分)。
已弃用 (Deprecated) API 将至少在 弃用周期 (deprecation period) 内保持功能正常(参见下面的“弃用周期”部分),以便开发者有时间迁移到替代 API。
已删除 (Deleted)
已永久移除的 API。从代码和文档中都已清理干净。
弃用策略¶
遵循以下步骤弃用和移除 API
讨论变更并收集初步反馈。
在代码和文档中明确标记 API 为已弃用(参见下面的“如何标记 API 状态”)。
在首次发布包含该已弃用 API 的版本后,听取用户反馈。未参与原始讨论的用户可能对不弃用或移除该 API 有充分的理由。
弃用周期过后,可以移除该 API(参见下面的“弃用周期”)。务必同时从文档中移除所有引用。
我们还使用弃用作为对现有接口进行破坏性更改的一种方式:例如,如果向方法添加非可选参数。为了在不影响现有用户的情况下进行此操作,请遵循以下步骤:
在一次提交中
创建满足新要求的新 API。
弃用旧 API,并建议用户迁移到新 API。
将旧 API 的用例迁移到新 API。
在弃用周期后删除旧 API。
如何标记 API 状态¶
在可能的情况下,ExecuTorch 代码使用语言标准的方式在代码中注释 API 生命周期状态。这使得 IDE 和其他工具更容易向开发者传达状态信息。
语言 | 代码 | 文档 |
Python |
在已弃用和实验性 API 的文档字符串中使用 |
|
C++ |
使用
使用 |
在 Doxygen 注释中以
在 Doxygen 注释中以 |
Java |
|
|
Objective-C |
|
|
Swift |
|
|
这些注解将触发静态和/或运行时警告,其中至少包含以下信息:
明确指出可迁移到的非弃用替代方案,或者明确说明没有替代方案;
指定该 API 实际可能被移除的最早版本(参见下面的“弃用周期”)。
弃用周期¶
这里我们建议在移除前至少等待 2 个小版本发布。例如,如果一个函数在 1.3.x 版本中被标记为 已弃用 (deprecated),那么它可以在 1.5.x 或更高版本中被 已删除 (deleted)。