diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0c37e3b3c..2ad23f84d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,8 @@ We actively welcome your pull requests (PRs). See the [testing section](#testing) for more information. 1. If you've changed APIs or added a new tool or feature, [update the documentation](#updating-documentation). +1. If you added an experimental API or deprecated an existing API, follow the + [API Life Cycle and Deprecation Policy](/docs/source/api-life-cycle.md). 1. Make sure your code follows the [style guides](#coding-style) and passes the [lint checks](#lintrunner). 1. If you haven't already, complete the [Contributor License Agreement ("CLA")](#contributor-license-agreement-cla). diff --git a/docs/source/_static/img/api_life_cycle.png b/docs/source/_static/img/api_life_cycle.png new file mode 100644 index 0000000000..47b8e7c318 Binary files /dev/null and b/docs/source/_static/img/api_life_cycle.png differ diff --git a/docs/source/api-life-cycle.md b/docs/source/api-life-cycle.md new file mode 100644 index 0000000000..fc729dbae8 --- /dev/null +++ b/docs/source/api-life-cycle.md @@ -0,0 +1,215 @@ +# ExecuTorch API Life Cycle and Deprecation Policy + +## API Life Cycle + +![name](_static/img/api_life_cycle.png) + +Each API of ExecuTorch falls into one of the following life cycle states: + +_Experimental_ + +- APIs in this stage are under active development and may change or be removed + at any time. That said, the expectation is that we will eventually promote it + to _Stable_, unless sufficient negative signals have been collected from the + community or better alternatives have been found. +- _Experimental_ APIs will be clearly marked (see the “How to Mark API State” + section below). +- _Experimental_ APIs may be changed or removed without notice, and developers + should expect no stability guarantees. + +_Stable_ + +- APIs are considered to be _Stable_ if they are not marked as _Experimental_ or + _Deprecated._ +- APIs in this stage have been thoroughly tested and are considered ready for + production use. +- The recommended best practice is to not deprecate stable APIs. When writing an + API, write it in such a way that it doesn’t need to be deprecated in the + future. +- _Stable_ APIs can be changed, but not in a breaking way. If breaking changes + have to be made, _Stable_ APIs will always transition to _Deprecated_ before + being broken/removed from the library. + +_Deprecated_ + +- APIs in this stage are no longer recommended for use and will be removed in a + future version of ExecuTorch. +- _Deprecated_ APIs will be clearly marked (see the “How to Mark API State” + section below). +- _Deprecated_ APIs will remain functional for at least the _deprecation period_ + (see the “Deprecation Period” section below) to allow developers time to + migrate to alternative APIs. + +_Deleted_ + +- APIs whose removal are made permanent. Cleaned up from both code and + documentation. + +## Deprecation Policy + +Follow these steps to deprecate and remove an API: + +1. Discuss the change and collect initial feedback. +2. Clearly mark the API deprecated in code and documentation (See “How to Mark + API State” below). +3. Listen to user feedback after the first release that deprecates the API. + Users who weren't involved in the original discussion may have good arguments + for not deprecating or removing the API. +4. Once the deprecation period has passed, the API may be removed (See + “Deprecation Period” below). Be sure to also remove references from the + documentation. + + +We also use deprecation as a way to make breaking changes to an existing +interface: for example, if adding a non-optional parameter to a method. To do +this without breaking existing users: + +1. In a single commit: + - Create a new API that meets the new requirements. + - Deprecate the old API and recommend that users move to the new API. +2. Migrate use cases from the old API to the new API. +3. Delete the old API after the deprecation period. + +## How to Mark API State + +When possible, the ExecuTorch code uses language-standard ways to annotate API +lifecycle state in the code. This makes it easier for IDEs and other tools to +communicate state to developers. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Language + Code + Documentation +
Python + + +Use the +typing_extensions.deprecated +decorator + +

+Use ExecuTorch's native experimental decorator (TODO not yet implemented) + +

+ +Use .. warning:: in the docstrings of deprecated and experimental +APIs. See +example +usage + + +
C++ + + +Use __ET_DEPRECATED macros. See example usage + +

+

+Use __ET_EXPERIMENTAL macros (TODO not yet implemented) + +

+ +Start Doxygen comments with DEPRECATED: See +example +usage + +

+

+Start Doxygen comments with EXPERIMENTAL: +

Java + + +Use java.lang.Deprecated + +

+

+ +Use androidx.annotation.RequiresOptIn + +

+

+

/**
+* @deprecated Use {@link #newMethod()} instead.
+*/
+
+

+

/**
+* Warning: This API is experimental.
+*/
+
Objective-C + +

+__attribute__((deprecated("Use newMethod instead"))); +

+

+__attribute__((experimental("Use newMethod instead"))); (TODO not yet implemented) +

+

+


+/**
+* @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. +

+ +The annotations would trigger static and/or runtime warning that contains at +least these information: + +1. Clearly point to the non-deprecated alternative to migrate to, or be clear if + there is no alternative; +2. Specify the earliest version in which the API may actually be removed (See + “Deprecation Period” below). + +## Deprecation Period + +Here we recommend waiting for at least 2 minor releases before the removal. For +example, if a function is marked as _deprecated_ in release 1.3.x, then it can +be _deleted_ in 1.5.x or later. diff --git a/docs/source/executorch-runtime-api-reference.rst b/docs/source/executorch-runtime-api-reference.rst index 20dbc631f2..008030b84d 100644 --- a/docs/source/executorch-runtime-api-reference.rst +++ b/docs/source/executorch-runtime-api-reference.rst @@ -6,6 +6,8 @@ The ExecuTorch C++ API provides an on-device execution framework for exported Py For a tutorial style introduction to the runtime API, check out the `runtime tutorial `__ and its `simplified `__ version. +For detailed information on how APIs evolve and the deprecation process, please refer to the `ExecuTorch API Life Cycle and Deprecation Policy `__. + Model Loading and Execution --------------------------- diff --git a/docs/source/export-to-executorch-api-reference.rst b/docs/source/export-to-executorch-api-reference.rst index 2150ac7f8c..5560e75e21 100644 --- a/docs/source/export-to-executorch-api-reference.rst +++ b/docs/source/export-to-executorch-api-reference.rst @@ -1,6 +1,8 @@ Export to ExecuTorch API Reference ---------------------------------- +For detailed information on how APIs evolve and the deprecation process, please refer to the `ExecuTorch API Life Cycle and Deprecation Policy `__. + .. automodule:: executorch.exir .. autofunction:: to_edge diff --git a/docs/source/index.rst b/docs/source/index.rst index 57dc2c4bcc..d8955c513e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -126,6 +126,7 @@ Topics in this section will help you get started with ExecuTorch. export-to-executorch-api-reference executorch-runtime-api-reference + api-life-cycle .. toctree:: :glob: