• 文档 >
  • API 生命周期和弃用策略
快捷方式

API 生命周期和弃用策略

API 生命周期

name

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

实验性 (Experimental)

  • 处于此阶段的 API 正在积极开发中,随时可能更改或删除。不过,除非从社区收集到足够的负面反馈或找到了更好的替代方案,否则我们期望最终将其提升为 稳定 (Stable) 版。

  • 实验性 (Experimental) API 将被明确标记(参见下面的“如何标记 API 状态”部分)。

  • 实验性 (Experimental) API 可能会在不通知的情况下更改或删除,开发者不应期望其具备稳定性保证。

稳定 (Stable)

  • 未标记为 实验性 (Experimental)已弃用 (Deprecated) 的 API 被视为 稳定 (Stable)

  • 处于此阶段的 API 已经过充分测试,被认为可用于生产环境。

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

  • 稳定 (Stable) API 可以更改,但不能是破坏性更改。如果必须进行破坏性更改,稳定 (Stable) API 将始终先转换为 已弃用 (Deprecated) 状态,然后才能从库中移除/发生破坏性更改。

已弃用 (Deprecated)

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

  • 已弃用 (Deprecated) API 将被明确标记(参见下面的“如何标记 API 状态”部分)。

  • 已弃用 (Deprecated) API 将至少在 弃用周期 (deprecation period) 内保持功能正常(参见下面的“弃用周期”部分),以便开发者有时间迁移到替代 API。

已删除 (Deleted)

  • 已永久移除的 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: 已弃用。请改用 newMethod()

/// - Warning: 此 API 是实验性的。

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

  1. 明确指出可迁移到的非弃用替代方案,或者明确说明没有替代方案;

  2. 指定该 API 实际可能被移除的最早版本(参见下面的“弃用周期”)。

弃用周期

这里我们建议在移除前至少等待 2 个小版本发布。例如,如果一个函数在 1.3.x 版本中被标记为 已弃用 (deprecated),那么它可以在 1.5.x 或更高版本中被 已删除 (deleted)

文档

查阅 PyTorch 的全面开发者文档

查看文档

教程

获取针对初学者和高级开发者的深度教程

查看教程

资源

查找开发资源并解答疑问

查看资源