ExecuTorch API 生命周期和弃用策略

API 生命周期

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

实验的

• 此阶段的 API 正在积极开发中，可能会更改或删除 随时。也就是说，我们期望我们最终会推广它 设置为 Stable，除非已从 社区或更好的替代方案。

• 实验的API 将被清楚地标记（请参阅“如何标记 API 状态” 部分）。

• 实验的API 可能会更改或删除，恕不另行通知，开发人员 应该不需要稳定性保证。

稳定

• 如果 API 未标记为 Experimental 或 Deprecated，则 API 被视为 Stable。

• 此阶段的 API 已经过全面测试，并被认为已准备就绪 生产使用。

• 建议的最佳实践是不要弃用稳定的 API。在编写 API 中，以不需要在 前途。

• 稳定API 可以更改，但不能以中断方式更改。如果重大更改 ，则 Stable API 将始终在 被破坏/从库中移除。

荒废的

• 不再建议使用此阶段的 API，并将在 ExecuTorch 的未来版本。

• 荒废的API 将被清楚地标记（请参阅“如何标记 API 状态” 部分）。

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

删除

• 其删除将永久删除的 API。从 code 和 文档。

弃用政策

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

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

2. 在代码和文档中明确标记已弃用的 API（请参阅“如何标记 API State”）。

3. 在弃用 API 的第一个版本发布后听取用户反馈。 未参与原始讨论的用户可能有很好的论点 没有弃用或删除 API。

4. 弃用期过后，可以删除 API（请参阅 “弃用期”）。请务必同时从 文档。

我们还使用弃用作为对现有 interface：例如，如果向方法添加非可选参数。待办事项 这不会破坏现有用户：

1. 在单个提交中：

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

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

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

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

如何标记 API 状态

在可能的情况下，ExecuTorch 代码使用语言标准方法来注释 API lifecycle 状态。这使得 IDE 和其他工具更容易 将状态传达给开发人员。

语言	法典	文档
蟒	使用 executorch.exir._warnings.deprecated 装饰器。 使用 executorch.exir._warnings.experimental 装饰器。	在 deprecated 和 experimental 的文档字符串中使用 蜜蜂属。查看示例 使用情况。.. warning::
C++	使用 annotation 宏。请参阅示例用法。ET_DEPRECATED 使用 annotation 宏。ET_EXPERIMENTAL	使用 See example 开始 Doxygen 注释 使用情况。DEPRECATED: 以 .EXPERIMENTAL:
爪哇岛	使用 java.lang.Deprecated。 使用 androidx.annotation.RequiresOptIn。	/** * @deprecated Use {@link #newMethod()} instead. */ /** * Warning: This API is experimental. */
目标-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. */
迅速	@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 或更高版本中删除。