API 生命週期和棄用策略

API 生命週期

每個 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)。