TorchScript API 生命周期和弃用政策

API 生命周期

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

实验

• 此阶段的API正在积极开发中，可能会随时更改或删除。尽管如此，我们期望最终将其提升为稳定版本，除非从社区收集到足够的负面信号或找到更好的替代方案。

• 实验性 API 会明确标注（请参见下方“如何标注API状态”部分）。

• 实验性 API 可能会随时更改或移除，开发者不应期待任何稳定性保证。

稳定版

• API 被认为是 稳定 的，如果它们没有被标记为 实验性 或 已弃用。

• 此阶段的API已经过充分测试，可视为准备就绪，可用于生产环境。

• 推荐的最佳实践是不要弃用稳定的 API。在编写 API 时，应以一种无需在未来弃用的方式进行编写。

• 稳定 的API可以更改，但不会以破坏性的方式更改。如果必须进行破坏性更改，稳定 的API将始终先过渡到已弃用，然后再从库中被破坏/移除。

已弃用

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

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

• 已弃用 的API将在至少 弃用期 (参见下方的“弃用期”部分) 内继续有效，以便开发者有时间 迁移到替代的API。

已删除

• APIs 其移除为永久性操作。已从代码和文档中清理。

弃用策略

按照以下步骤弃用并移除 API：

1. 讨论变更并收集初始反馈。

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

3. 在首次发布后，听取用户对弃用 API 的反馈。 未参与原始讨论的用户可能有合理的理由，认为不应弃用或删除该 API。

4. 一旦弃用期结束，该 API 可能会被移除（参见下方“弃用期”部分）。请确保同时从文档中移除相关引用。

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

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("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可能实际被移除的最早版本（参见下方“弃用期”）。

弃用期

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