ExecuTorch API 生命周期和弃用策略¶
API 生命周期¶
ExecuTorch 的每个 API 都属于以下生命周期状态之一
实验性
此阶段的 API 处于积极开发中,可能随时更改或删除。也就是说,我们预计最终会将其提升到稳定状态,除非从社区收集到足够的负面信号或发现了更好的替代方案。
实验性 API 将被明确标记(请参阅下面的“如何标记 API 状态”部分)。
实验性 API 可能会在未经通知的情况下更改或删除,开发人员不应期望任何稳定性保证。
稳定
如果 API 未标记为实验性或已弃用,则视为稳定。
此阶段的 API 已过全面测试,并被认为已准备好投入生产使用。
建议的最佳实践是不弃用稳定 API。在编写 API 时,请以一种在将来不需要弃用的方式编写它。
稳定 API 可以更改,但不能以破坏性的方式更改。如果必须进行破坏性更改,则稳定 API 将始终在从库中破坏/删除之前转换为已弃用。
已弃用
此阶段的 API 不再建议使用,并且将在 ExecuTorch 的未来版本中删除。
已弃用 API 将被明确标记(请参阅下面的“如何标记 API 状态”部分)。
已弃用 API 将至少在弃用期内保持功能(请参阅下面的“弃用期”部分),以便开发人员有时间迁移到替代 API。
已删除
已永久删除的 API。已从代码和文档中清除。
弃用策略¶
请按照以下步骤弃用和删除 API
讨论更改并收集初步反馈。
在代码和文档中明确标记 API 已弃用(请参阅下面的“如何标记 API 状态”)。
在第一个弃用 API 的版本发布后,倾听用户反馈。未参与最初讨论的用户可能对不弃用或删除 API 有很好的理由。
弃用期过后,可以删除 API(请参阅下面的“弃用期”)。请确保也从文档中删除引用。
我们还使用弃用作为对现有接口进行破坏性更改的一种方式:例如,如果向方法添加非可选参数。为此,无需破坏现有用户
在一个提交中
创建一个满足新要求的新 API。
弃用旧 API 并建议用户迁移到新 API。
将用例从旧 API 迁移到新 API。
弃用期过后,删除旧 API。
如何标记 API 状态¶
如果可能,ExecuTorch 代码使用语言标准方法在代码中注释 API 生命周期状态。这使 IDE 和其他工具更容易将状态传达给开发人员。
语言 | 代码 | 文档 |
Python |
在已弃用和实验性 API 的文档字符串中使用 |
|
C++ |
使用
使用 |
以
以 |
Java |
|
|
Objective-C |
|
|
Swift |
|
|
这些注释将触发静态和/或运行时警告,其中至少包含以下信息
明确指出要迁移到的非弃用替代方案,或者如果不存在替代方案,则明确说明;
指定 API 实际可能被删除的最早版本(请参阅下面的“弃用期”)。
弃用期¶
在这里,我们建议在删除之前至少等待 2 个次要版本。例如,如果某个函数在 1.3.x 版本中标记为已弃用,则它可以在 1.5.x 或更高版本中删除。