Skip to content

Commit 54f8932

Browse files
Olivia-liuOlivia-liu
authored
API life cycle and deprecation policy in official documentation
Differential Revision: D60692061 Pull Request resolved: #4529
1 parent a9ed835 commit 54f8932

File tree

6 files changed

+222
-0
lines changed

6 files changed

+222
-0
lines changed

‎CONTRIBUTING.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ We actively welcome your pull requests (PRs).
2323
See the [testing section](#testing) for more information.
2424
1. If you've changed APIs or added a new tool or feature, [update the
2525
documentation](#updating-documentation).
26+
1. If you added an experimental API or deprecated an existing API, follow the
27+
[API Life Cycle and Deprecation Policy](/docs/source/api-life-cycle.md).
2628
1. Make sure your code follows the [style guides](#coding-style) and passes the
2729
[lint checks](#lintrunner).
2830
1. If you haven't already, complete the [Contributor License Agreement ("CLA")](#contributor-license-agreement-cla).

‎docs/source/_static/img/api_life_cycle.png

226 KB
Loading

‎docs/source/api-life-cycle.md

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# ExecuTorch API Life Cycle and Deprecation Policy
2+
3+
## API Life Cycle
4+
5+
![name](_static/img/api_life_cycle.png)
6+
7+
Each API of ExecuTorch falls into one of the following life cycle states:
8+
9+
_Experimental_
10+
11+
- APIs in this stage are under active development and may change or be removed
12+
at any time. That said, the expectation is that we will eventually promote it
13+
to _Stable_, unless sufficient negative signals have been collected from the
14+
community or better alternatives have been found.
15+
- _Experimental_ APIs will be clearly marked (see the “How to Mark API State”
16+
section below).
17+
- _Experimental_ APIs may be changed or removed without notice, and developers
18+
should expect no stability guarantees.
19+
20+
_Stable_
21+
22+
- APIs are considered to be _Stable_ if they are not marked as _Experimental_ or
23+
_Deprecated._
24+
- APIs in this stage have been thoroughly tested and are considered ready for
25+
production use.
26+
- The recommended best practice is to not deprecate stable APIs. When writing an
27+
API, write it in such a way that it doesn’t need to be deprecated in the
28+
future.
29+
- _Stable_ APIs can be changed, but not in a breaking way. If breaking changes
30+
have to be made, _Stable_ APIs will always transition to _Deprecated_ before
31+
being broken/removed from the library.
32+
33+
_Deprecated_
34+
35+
- APIs in this stage are no longer recommended for use and will be removed in a
36+
future version of ExecuTorch.
37+
- _Deprecated_ APIs will be clearly marked (see the “How to Mark API State”
38+
section below).
39+
- _Deprecated_ APIs will remain functional for at least the _deprecation period_
40+
(see the “Deprecation Period” section below) to allow developers time to
41+
migrate to alternative APIs.
42+
43+
_Deleted_
44+
45+
- APIs whose removal are made permanent. Cleaned up from both code and
46+
documentation.
47+
48+
## Deprecation Policy
49+
50+
Follow these steps to deprecate and remove an API:
51+
52+
1. Discuss the change and collect initial feedback.
53+
2. Clearly mark the API deprecated in code and documentation (See “How to Mark
54+
API State” below).
55+
3. Listen to user feedback after the first release that deprecates the API.
56+
Users who weren't involved in the original discussion may have good arguments
57+
for not deprecating or removing the API.
58+
4. Once the deprecation period has passed, the API may be removed (See
59+
“Deprecation Period” below). Be sure to also remove references from the
60+
documentation.
61+
62+
63+
We also use deprecation as a way to make breaking changes to an existing
64+
interface: for example, if adding a non-optional parameter to a method. To do
65+
this without breaking existing users:
66+
67+
1. In a single commit:
68+
- Create a new API that meets the new requirements.
69+
- Deprecate the old API and recommend that users move to the new API.
70+
2. Migrate use cases from the old API to the new API.
71+
3. Delete the old API after the deprecation period.
72+
73+
## How to Mark API State
74+
75+
When possible, the ExecuTorch code uses language-standard ways to annotate API
76+
lifecycle state in the code. This makes it easier for IDEs and other tools to
77+
communicate state to developers.
78+
79+
<table>
80+
<tr>
81+
<td><strong>Language</strong>
82+
</td>
83+
<td><strong>Code</strong>
84+
</td>
85+
<td><strong>Documentation</strong>
86+
</td>
87+
</tr>
88+
<tr>
89+
<td>Python
90+
</td>
91+
<td>
92+
93+
Use the
94+
<a href="https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.deprecated">typing_extensions.deprecated</a>
95+
decorator
96+
97+
<p>
98+
Use ExecuTorch's native experimental decorator (TODO not yet implemented)
99+
100+
</td>
101+
<td>
102+
103+
Use <code>.. warning::</code> in the docstrings of deprecated and experimental
104+
APIs. See
105+
<a href="https://github.com/pytorch/pytorch/blob/cd8bbdc71a0258292381a7d54c8b353988d02ff4/torch/nn/utils/stateless.py#L170">example
106+
usage</a>
107+
108+
</ul>
109+
</td>
110+
</tr>
111+
<tr>
112+
<td>C++
113+
</td>
114+
<td>
115+
116+
Use <code>__ET_DEPRECATED</code> macros. See <a href="https://github.com/pytorch/executorch/blob/8e0f856ee269b319ac4195509cf31e3f548aa0e8/runtime/executor/program.h#L81">example usage</a>
117+
118+
<p>
119+
<p>
120+
Use <code>__ET_EXPERIMENTAL</code> macros (TODO not yet implemented)
121+
</ul>
122+
</td>
123+
<td>
124+
125+
Start Doxygen comments with <code>DEPRECATED:</code> See
126+
<a href="https://github.com/pytorch/executorch/blob/9d859653ae916d0a72f6b2b5c5925bed38832140/runtime/executor/program.h#L139">example
127+
usage</a>
128+
129+
<p>
130+
<p>
131+
Start Doxygen comments with <code>EXPERIMENTAL:</code>
132+
</td>
133+
</tr>
134+
<tr>
135+
<td>Java
136+
</td>
137+
<td>
138+
139+
Use <a href="https://docs.oracle.com/javase/9/docs/api/java/lang/Deprecated.html">java.lang.Deprecated</a>
140+
141+
<p>
142+
<p>
143+
144+
Use <a href="https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:docs/api_guidelines/annotations.md">androidx.annotation.RequiresOptIn</a>
145+
146+
</td>
147+
<td>
148+
<p>
149+
<pre><code>/**
150+
* @deprecated Use {@link #newMethod()} instead.
151+
*/
152+
</code></pre>
153+
<p>
154+
<pre><code>/**
155+
* Warning: This API is experimental.
156+
*/</code></pre>
157+
</td>
158+
</tr>
159+
<tr>
160+
<td>Objective-C
161+
</td>
162+
<td>
163+
<p>
164+
<code>__attribute__((deprecated("Use newMethod instead")));</code>
165+
<p>
166+
<p>
167+
<code>__attribute__((experimental("Use newMethod instead")));</code> (TODO not yet implemented)
168+
</td>
169+
<td>
170+
<p>
171+
<pre><code>
172+
/**
173+
* @deprecated Use `newMethod` instead.
174+
*/
175+
</code></pre>
176+
<p>
177+
<pre><code>
178+
/**
179+
* @experimental This API is experimental.
180+
*/</code></pre>
181+
<p>
182+
</td>
183+
</tr>
184+
<tr>
185+
<td>Swift
186+
</td>
187+
<td>
188+
<p>
189+
<code>@available(*, deprecated, message: "Use newMethod instead")</code>
190+
<p>
191+
<p>
192+
<code>@available(*, message: "This API is experimental")</code>
193+
</td>
194+
<td>
195+
<p>
196+
<code>/// - Warning: Deprecated. Use `newMethod()` instead.</code>
197+
<p>
198+
<code>/// - Warning: This API is experimental.</code>
199+
</td>
200+
</tr>
201+
</table>
202+
203+
The annotations would trigger static and/or runtime warning that contains at
204+
least these information:
205+
206+
1. Clearly point to the non-deprecated alternative to migrate to, or be clear if
207+
there is no alternative;
208+
2. Specify the earliest version in which the API may actually be removed (See
209+
“Deprecation Period” below).
210+
211+
## Deprecation Period
212+
213+
Here we recommend waiting for at least 2 minor releases before the removal. For
214+
example, if a function is marked as _deprecated_ in release 1.3.x, then it can
215+
be _deleted_ in 1.5.x or later.

‎docs/source/executorch-runtime-api-reference.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ The ExecuTorch C++ API provides an on-device execution framework for exported Py
66
For a tutorial style introduction to the runtime API, check out the
77
`runtime tutorial <running-a-model-cpp-tutorial.html>`__ and its `simplified <extension-module.html>`__ version.
88

9+
For detailed information on how APIs evolve and the deprecation process, please refer to the `ExecuTorch API Life Cycle and Deprecation Policy <api-life-cycle.html>`__.
10+
911
Model Loading and Execution
1012
---------------------------
1113

‎docs/source/export-to-executorch-api-reference.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
Export to ExecuTorch API Reference
22
----------------------------------
33

4+
For detailed information on how APIs evolve and the deprecation process, please refer to the `ExecuTorch API Life Cycle and Deprecation Policy <api-life-cycle.html>`__.
5+
46
.. automodule:: executorch.exir
57
.. autofunction:: to_edge
68

‎docs/source/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ Topics in this section will help you get started with ExecuTorch.
126126

127127
export-to-executorch-api-reference
128128
executorch-runtime-api-reference
129+
api-life-cycle
129130

130131
.. toctree::
131132
:glob:

0 commit comments

Comments
 (0)