ExecuTorch API生命週期與棄用政策

API 生命週期

ExecuTorch 的每個 API 都屬於以下生命週期狀態之一

實驗性

• 此階段的 API 正在積極開發中，可能隨時更改或移除。儘管如此，我們的期望是最終將其提升為穩定，除非從社群收集到足夠的負面訊號，或發現更好的替代方案。

• 實驗性 API 將被清楚標記（請參閱下面的「如何標記 API 狀態」部分）。

• Experimental (實驗性) 的 API 可能會在沒有通知的情況下變更或移除，開發者不應期望有任何穩定性保證。

Stable (穩定)

• 如果 API 沒有標記為 Experimental (實驗性) 或 Deprecated (已棄用)，則視為 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 的 docstring 中使用 .. 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("請改用 newMethod"))); __attribute__((deprecated("此 API 為實驗性，可能會在沒有通知的情況下變更。")));	/** * @deprecated Use `newMethod` instead. */ /** * @experimental This API is experimental. */
Swift	@available(*, deprecated, message: "請改用 newMethod") @available(*, message: "此 API 為實驗性")	/// - Warning: 已棄用。 請改用 `newMethod()`。 /// - Warning: 此 API 為實驗性。

註解將觸發靜態和/或執行時警告，其中至少包含以下資訊

1. 清楚地指出要遷移到的非已棄用替代方案，或者清楚地表明沒有替代方案；

2. 指定實際移除 API 的最早版本（請參閱下面的「棄用期」）。

棄用期

在這裡，我們建議在移除之前至少等待 2 個次要版本。 例如，如果一個函數在 1.3.x 版本中標記為 deprecated (已棄用)，則可以在 1.5.x 或更高版本中將其 deleted (刪除)。