API 生命周期和弃用策略

API 生命周期

ExecuTorch 的每个 API 都属于以下生命周期状态之一

实验性

• 此阶段的 API 正在积极开发中，可能会随时更改或删除。不过，我们的期望是最终会将其提升到“稳定”状态，除非从社区收集到足够多的负面信号或找到了更好的替代方案。

• “实验性” API 将会明确标记（参见下面的“如何标记 API 状态”部分）。

• “实验性” API 可能会在不通知的情况下进行更改或删除，开发人员应预期没有任何稳定性保证。

稳定

• 如果 API 未被标记为“实验性”或“已弃用”，则认为它是“稳定”的。

• 此阶段的 API 已经过彻底测试，并被认为已准备好投入生产使用。

• 推荐的最佳实践是不弃用稳定 API。在编写 API 时，应以不需将来弃用的方式编写。

• “稳定” API 可以更改，但不能以破坏性方式更改。如果必须进行破坏性更改，“稳定” API 在被破坏/从库中删除之前，总是会先过渡到“已弃用”状态。

已弃用

• 此阶段的 API 不再推荐使用，并且将在 ExecuTorch 的未来版本中删除。

• “已弃用” API 将会明确标记（参见下面的“如何标记 API 状态”部分）。

• “已弃用” API 将至少在“弃用期”（参见下面的“弃用期”部分）内保持功能，以便开发人员有时间迁移到替代 API。

已删除

• API 的移除被永久执行。已从代码和文档中清理。

弃用策略

请按照以下步骤弃用和删除 API：

1. 讨论更改并收集初步反馈。

2. 在代码和文档中明确标记 API 已弃用（参见下面的“如何标记 API 状态”）。

3. 在首次发布弃用 API 的版本后，倾听用户反馈。未参与原始讨论的用户可能对不弃用或删除 API 有充分的理由。

4. 弃用期过后，API 可能会被删除（参见下面的“弃用期”）。请务必同时删除文档中的引用。

我们还使用弃用作为对现有接口进行破坏性更改的一种方式：例如，如果向方法添加了非可选参数。要做到这一点而不破坏现有用户：

1. 一次提交

   • 创建一个满足新要求的新 API。

   • 弃用旧 API 并建议用户迁移到新 API。

2. 将用例从旧 API 迁移到新 API。

3. 在弃用期后删除旧 API。

如何标记 API 状态

在可能的情况下，ExecuTorch 代码使用语言标准的各种方式来注解代码中的 API 生命周期状态。这使得 IDE 和其他工具更容易向开发人员传达状态。

语言	代码	文档
Python	使用 executorch.exir._warnings.deprecated 装饰器。 使用 executorch.exir._warnings.experimental 装饰器。	在已弃用和实验性 API 的文档字符串中使用 .. warning::。参见 示例用法。
C++	使用 ET_DEPRECATED 注解宏。参见 示例用法。 使用 ET_EXPERIMENTAL 注解宏。	Doxygen 注释以 DEPRECATED: 开头。参见 示例用法。 Doxygen 注释以 EXPERIMENTAL: 开头。
Java	使用 java.lang.Deprecated。 使用 androidx.annotation.RequiresOptIn。	/** * @deprecated Use {@link #newMethod()} instead. */ /** * Warning: This API is experimental. */
Objective-C	__attribute__((deprecated("Use newMethod instead"))); __attribute__((deprecated("This API is experimental and may change without notice.")));	/** * @deprecated Use `newMethod` instead. */ /** * @experimental This API is experimental. */
Swift	@available(*, deprecated, message: "Use newMethod instead") @available(*, message: "This API is experimental")	/// - Warning: Deprecated. Use `newMethod()` instead. /// - Warning: This API is experimental.

这些注解将触发静态和/或运行时警告，其中至少包含以下信息：

1. 清楚地指出要迁移到的非弃用替代方案，或者在没有替代方案时要明确说明；

2. 指定 API 可能实际被删除的最早版本（参见下面的“弃用期”）。

弃用期

我们建议在删除之前至少等待 2 个次要版本。例如，如果一个函数在 1.3.x 版本中被标记为“已弃用”，那么它可以在 1.5.x 或更高版本中被“删除”。