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

ExecuTorch API 生命周期和弃用策略

API 生命周期

name

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("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 或更高版本中删除

文档

访问 PyTorch 的全面开发者文档

查看文档

教程

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

查看教程

资源

查找开发资源并获得问题的解答

查看资源