Skip to content

Commit 026d0b1

Browse files
Olivia-liufacebook-github-bot
Olivia-liu
authored and
facebook-github-bot
committed
API life cycle and deprecation policy in official documentation (#4529)
Summary: Pull Request resolved: #4529 For reviewers: to comment easily, please review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing Differential Revision: D60692061
1 parent fbc183f commit 026d0b1

File tree

5 files changed

+192
-0
lines changed

5 files changed

+192
-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: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# ExecuTorch API Life Cycle and Deprecation Policy
2+
3+
4+
## API Life Cycle
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+
10+
<table>
11+
<tr>
12+
<td>Life Cycle State
13+
</td>
14+
<td>Rules
15+
</td>
16+
</tr>
17+
<tr>
18+
<td><em>Experimental</em>
19+
</td>
20+
<td>
21+
<ul>
22+
23+
<li>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 <em>stable</em>, unless sufficient negative signals have been collected from the community or better alternatives have been found.
24+
25+
<li><em>Experimental</em> APIs will be clearly marked (see the “How to Mark?” section below).
26+
27+
<li><em>Experimental</em> APIs may be changed or removed without notice, and developers should expect no stability guarantees.
28+
</li>
29+
</ul>
30+
</td>
31+
</tr>
32+
<tr>
33+
<td><em>Stable</em>
34+
</td>
35+
<td>
36+
<ul>
37+
38+
<li>APIs are considered to be <em>stable</em> if they are not marked as <em>Experimental</em> or <em>Deprecated.</em>
39+
40+
<li>APIs in this stage have been thoroughly tested and are considered ready for production use.
41+
42+
<li>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.
43+
44+
<li><em>Stable</em> APIs can be changed, but not in a BC-breaking way. If BC-breaking changes have to be made, <em>stable</em> APIs will always transition to <em>Deprecated</em> before being broken/removed from the library.
45+
</li>
46+
</ul>
47+
</td>
48+
</tr>
49+
<tr>
50+
<td><em>Deprecated</em>
51+
</td>
52+
<td>
53+
<ul>
54+
55+
<li>APIs in this stage are no longer recommended for use and will be removed in a future version of ExecuTorch.
56+
57+
<li><em>Deprecated</em> APIs will be clearly marked (see the “How to Mark?” section below).
58+
59+
<li><em>Deprecated</em> APIs will remain functional for at least <em>deprecation period</em> (see the “Deprecation Period” section below) to allow developers time to migrate to alternative APIs, unless there’s extreme circumstances, like security issues having to be fixed.
60+
</li>
61+
</ul>
62+
</td>
63+
</tr>
64+
<tr>
65+
<td><em>Deleted</em>
66+
</td>
67+
<td>
68+
<ul>
69+
70+
<li>APIs whose removal are made permanent. Cleaned up from both code and documentation.
71+
</li>
72+
</ul>
73+
</td>
74+
</tr>
75+
</table>
76+
77+
78+
79+
## Deprecation Policy
80+
81+
Follow these steps to deprecate an API:
82+
83+
1. Discuss the change and collect initial feedback.
84+
2. Clearly mark the API deprecated in code and documentation (See “How to Mark?” below). The mark would trigger static and/or runtime warning that contains at least these information (or in documentation only, if a warning message is not feasible):
85+
1. Clearly point to the non-deprecated alternative to migrate to, or be clear if there is no alternative.
86+
2. Specify the earliest version in which the API may actually be removed (See “Deprecation Period” below)
87+
3. Watch out for feedback. Users who weren’t involved in the original discussion can now comment. Maybe reconsider the deprecation.
88+
4. The API removal may now be made permanent having reached the declared version. Make sure documentation is also cleaned up.
89+
90+
91+
In the case that a breaking change has to be made to an existing interface, for example, if a non-optional parameter has to be added to a method, then we treat this as a deprecation case. Steps to take:
92+
93+
94+
1. Create a new API that meets the new requirements.
95+
2. Migrate use cases from the old API to the new API.
96+
3. Deprecate the old API.
97+
98+
99+
## How to Mark?
100+
101+
We want to make the best effort to mark in the most standard way possible, so that it’s easier for users to integrate with their dev tools, like Linters.
102+
103+
<table>
104+
<tr>
105+
<td><strong>API</strong>
106+
</td>
107+
<td><strong>Code</strong>
108+
</td>
109+
<td><strong>Documentation</strong>
110+
</td>
111+
</tr>
112+
<tr>
113+
<td>Python
114+
</td>
115+
<td>
116+
<ul>
117+
118+
<li><em>Deprecated</em>: use <a href="https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.deprecated">typing_extensions.deprecated</a> decorator
119+
120+
<li><em>Experimental</em>: use ExecuTorch's native experimental (TODO not yet implemented) decorator
121+
</li>
122+
</ul>
123+
</td>
124+
<td>
125+
<ul>
126+
127+
<li>Use <code>.. warning::</code> in docstring of deprecated and experimental APIs, see example usage <a href="https://github.com/pytorch/pytorch/blob/cd8bbdc71a0258292381a7d54c8b353988d02ff4/torch/nn/utils/stateless.py#L170">here</a>.
128+
</li>
129+
</ul>
130+
</td>
131+
</tr>
132+
<tr>
133+
<td>C++
134+
</td>
135+
<td>
136+
<ul>
137+
138+
<li>Use the <code>__ET_DEPRECATED</code> and (TODO not yet implemented) <code>__ET_EXPERIMENTAL</code> macro, see example usage <a href="https://github.com/pytorch/executorch/blob/8e0f856ee269b319ac4195509cf31e3f548aa0e8/runtime/executor/program.h#L81">here</a>.
139+
</li>
140+
</ul>
141+
</td>
142+
<td>
143+
<ul>
144+
145+
<li>Start docstring with “DEPRECATED” and “EXPERIMENTAL”, see example usage <a href="https://github.com/pytorch/executorch/blob/9d859653ae916d0a72f6b2b5c5925bed38832140/runtime/executor/program.h#L139">here</a>.
146+
</li>
147+
</ul>
148+
</td>
149+
</tr>
150+
<tr>
151+
<td>Android
152+
</td>
153+
<td>TODO
154+
</td>
155+
<td>TODO
156+
</td>
157+
</tr>
158+
<tr>
159+
<td>iOS
160+
</td>
161+
<td>TODO
162+
</td>
163+
<td>TODO
164+
</td>
165+
</tr>
166+
</table>
167+
168+
169+
## Deprecation Period
170+
171+
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.
172+
173+
174+
## Future Enhancements
175+
176+
177+
### Enforcement
178+
179+
We want to implement automated tests to monitor:
180+
* Were any BC-breaking changes made to stable APIs?
181+
* Did the removal of an deprecated API happen not sooner than the promised period?
182+
183+
184+
### Auto migration
185+
186+
The current deprecation policy still requires users to take actions to migrate off from deprecated APIs. Ideally, we should automate this process. We want to leverage tools like [TorchFix](https://pypi.org/project/TorchFix/) to auto-migrate uses of deprecated APIs when possible.

‎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

0 commit comments

Comments
 (0)