ExecuTorch 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 注释宏。	以 DEPRECATED: 开头 Doxygen 注释。 请参阅 示例用法。 以 EXPERIMENTAL: 开头 Doxygen 注释。
Java	使用 java.lang.Deprecated。 使用 androidx.annotation.RequiresOptIn。	/** * @deprecated Use {@link #newMethod()} instead. */ /** * Warning: This API is experimental. */
Objective-C	__attribute__((deprecated("使用 newMethod 代替"))); __attribute__((deprecated("此 API 是实验性的，可能会在没有通知的情况下更改。")));	/** * @deprecated Use `newMethod` instead. */ /** * @experimental This API is experimental. */
Swift	@available(*, deprecated, message: "使用 newMethod 代替") @available(*, message: "此 API 是实验性的")	/// - Warning: 已弃用。 使用 `newMethod()` 代替。 /// - Warning: 此 API 是实验性的。

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

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

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

弃用期

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