API life cycle and deprecation policy in official documentation #4529

Olivia-liu · 2024-08-02T22:30:06Z

Summary:

This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs.
The doc has some TODO items we can either address in this diff or with follow-up diffs.

For Meta reviewers: to comment easily, please review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing

Differential Revision: D60692061

pytorch-bot · 2024-08-02T22:30:08Z

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/4529

📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

✅ No Failures

As of commit 69865ad with merge base f1b741e ():
💚 Looks good so far! There are no failures yet. 💚

This comment was automatically generated by Dr. CI and updates every 15 minutes.

facebook-github-bot · 2024-08-02T22:30:34Z

This pull request was exported from Phabricator. Differential Revision: D60692061

facebook-github-bot · 2024-08-02T22:37:20Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 For reviewers: to comment easily, please review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing Differential Revision: D60692061

facebook-github-bot · 2024-08-02T22:52:25Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing Differential Revision: D60692061

facebook-github-bot · 2024-08-02T23:04:38Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing Differential Revision: D60692061

dbort

The structure looks great; thanks for adding this.

docs/source/api-life-cycle.md

facebook-github-bot · 2024-08-07T02:45:29Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. ***For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing*** Differential Revision: D60692061

facebook-github-bot · 2024-08-07T02:49:37Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. ***For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing*** Differential Revision: D60692061

facebook-github-bot · 2024-08-07T16:50:45Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. ***For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing*** Differential Revision: D60692061

dbort

Thanks for the changes! Remaining comments are about consistency throughout the doc.

dbort · 2024-08-07T16:58:50Z

docs/source/api-life-cycle.md

+   </td>
+  </tr>
+  <tr>
+   <td>Android


Instead of "Android" and "Apple", it'd be more consistent to have rows for "Java", "Swift", "Objective C". The first column of this table is really "Language".

dbort · 2024-08-07T17:00:27Z

docs/source/api-life-cycle.md

+  <tr>
+   <td>Android
+   </td>
+   <td>Deprecated: use <a href="https://docs.oracle.com/javase/9/docs/api/java/lang/Deprecated.html">java.lang.Deprecated</a>


Consistency: This uses non-italicized "Deprecated" and "Experimental", but the first row italicizes them. The C++ row doesn't even mention "Deprecated" or "Experimental" directly. And the Android/Apple rows only seem to talk about deprecated code, not experimental code.

Ideally, each row of this table would be consistent with all of the other rows.

dbort · 2024-08-07T17:02:49Z

docs/source/api-life-cycle.md

+/**
+<p>
+* @deprecated Use `newMethod` instead.
+<p>
+*/


Would be nice to make these code blocks, though I don't know if that works in a table.

Suggested change

/**



* @deprecated Use `newMethod` instead.



*/

/**

<pre><code>



* @deprecated Use `newMethod` instead.



</code></pre>

*/

Or maybe triple-backquote will work here.

Same for the swift example

Using <code> and  doesn't render very well in chrome (see screenshot). Does <pre><code> work like https://stackoverflow.com/a/4611735 suggests?

docs/source/api-life-cycle.md

dbort · 2024-08-07T17:24:40Z

docs/source/api-life-cycle.md

+   </td>
+   <td>Deprecated: use <a href="https://docs.oracle.com/javase/9/docs/api/java/lang/Deprecated.html">java.lang.Deprecated</a>
+<p>
+Experimental: use <a href="https://developer.android.com/reference/androidx/annotation/RequiresOptIn">androidx.annotation.RequiresOptIn</a>


Maybe point to https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:docs/api_guidelines/annotations.md as well (or instead), which give more guidance about using this annotation.

dbort · 2024-08-07T17:30:31Z

docs/source/api-life-cycle.md

+<p>
+/**
+<p>
+Warning: This API is experimental


Our style guide prefers full sentences, ending with periods.

Suggested change

Warning: This API is experimental

Warning: This API is experimental.

facebook-github-bot · 2024-08-09T23:17:50Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. ***For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing*** Differential Revision: D60692061

facebook-github-bot · 2024-08-09T23:23:29Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. ***For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing*** Differential Revision: D60692061

facebook-github-bot · 2024-08-13T22:19:03Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. ***For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing*** Differential Revision: D60692061

facebook-github-bot · 2024-08-13T22:57:55Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. ***For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing*** Differential Revision: D60692061

facebook-github-bot · 2024-08-13T23:57:31Z

This pull request was exported from Phabricator. Differential Revision: D60692061

facebook-github-bot · 2024-08-14T00:55:24Z

This pull request was exported from Phabricator. Differential Revision: D60692061

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. ***For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing*** Differential Revision: D60692061

dbort

Thanks for all of the changes. A couple final issues, but I'll approve now to move things along.

dbort · 2024-08-14T17:58:23Z

docs/source/api-life-cycle.md

+/**
+<p>
+* @deprecated Use `newMethod` instead.
+<p>
+*/


Using <code> and  doesn't render very well in chrome (see screenshot). Does <pre><code> work like https://stackoverflow.com/a/4611735 suggests?

dbort · 2024-08-14T18:03:39Z

docs/source/api-life-cycle.md

+<code>__attribute__((deprecated("Use newMethod instead")));</code>
+<p>
+<p>
+<code>__attribute__((experimental("Use newMethod instead")));</code> (TODO not yet implemented)


I don't know if it's possible to implement an attribute like this; they're typically defined by the toolchain.

@shoumikhin Could you comment on this please? I've chatted with Anthony offline and IIUC, there's a mapping between the Objective-C annotations and the CPP macros. So if the CPP __ET_DEPRECATED and __ET_EXPERIMENTAL can be implemented, then we can implement these.

Oh I meant we can use the deprecated annotation for experental features too, since there's no dedicated experimental annotation available. Thus __ET_EXPERIMENTAL is gonna be defined the same as deprecated, but with a different error message.

…rch#4529) Summary: Pull Request resolved: pytorch#4529 This diff adds a new page to the ET public documentation site that establishes the API life cycle and deprecation policy. It's also been linked to from related docs. The doc has some TODO items we can either address in this diff or with follow-up diffs. ***For Meta reviewers: to comment easily, you can review in https://docs.google.com/document/d/1FJmsWoP544bF0Xe3SeREcLAbKPqgrxulScBdak0UoVs/edit?usp=sharing*** Reviewed By: dbort Differential Revision: D60692061

facebook-github-bot · 2024-08-15T01:04:32Z

This pull request was exported from Phabricator. Differential Revision: D60692061

Differential Revision: D60692061 Pull Request resolved: pytorch#4529

facebook-github-bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Aug 2, 2024

facebook-github-bot added the fb-exported label Aug 2, 2024

Olivia-liu force-pushed the export-D60692061 branch from 358a793 to 026d0b1 Compare August 2, 2024 22:37

Olivia-liu force-pushed the export-D60692061 branch from 026d0b1 to e6b8fec Compare August 2, 2024 22:52

Olivia-liu force-pushed the export-D60692061 branch from e6b8fec to 2a8207f Compare August 2, 2024 23:04

dbort requested changes Aug 5, 2024

View reviewed changes

Olivia-liu force-pushed the export-D60692061 branch from 2a8207f to 313ade0 Compare August 7, 2024 02:45

Olivia-liu force-pushed the export-D60692061 branch from 313ade0 to dd99c24 Compare August 7, 2024 02:49

Olivia-liu force-pushed the export-D60692061 branch from dd99c24 to 0d4355c Compare August 7, 2024 16:50

Olivia-liu requested a review from dbort August 7, 2024 17:13

dbort requested changes Aug 7, 2024

View reviewed changes

Olivia-liu force-pushed the export-D60692061 branch from 0d4355c to 140e08e Compare August 9, 2024 23:17

Olivia-liu force-pushed the export-D60692061 branch from 140e08e to d92f447 Compare August 9, 2024 23:23

Olivia-liu force-pushed the export-D60692061 branch from d92f447 to c2e551e Compare August 13, 2024 22:19

Olivia-liu force-pushed the export-D60692061 branch from c2e551e to 3109a00 Compare August 13, 2024 22:58

Olivia-liu force-pushed the export-D60692061 branch from 3109a00 to 81279d8 Compare August 13, 2024 23:57

Olivia-liu requested a review from dbort August 14, 2024 00:49

Olivia-liu force-pushed the export-D60692061 branch from 81279d8 to 2528d75 Compare August 14, 2024 00:55

dbort approved these changes Aug 14, 2024

View reviewed changes

Olivia-liu force-pushed the export-D60692061 branch from 2528d75 to 69865ad Compare August 15, 2024 01:04

facebook-github-bot merged commit 54f8932 into pytorch:main Aug 15, 2024
36 of 37 checks passed

kirklandsign pushed a commit to kirklandsign/executorch that referenced this pull request Aug 15, 2024

API life cycle and deprecation policy in official documentation

9e3fe56

Differential Revision: D60692061 Pull Request resolved: pytorch#4529

	Warning: This API is experimental
	Warning: This API is experimental.

API life cycle and deprecation policy in official documentation #4529

API life cycle and deprecation policy in official documentation #4529

Uh oh!

Conversation

Olivia-liu commented Aug 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pytorch-bot bot commented Aug 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/4529

✅ No Failures

Uh oh!

facebook-github-bot commented Aug 2, 2024

Uh oh!

facebook-github-bot commented Aug 2, 2024

Uh oh!

facebook-github-bot commented Aug 2, 2024

Uh oh!

facebook-github-bot commented Aug 2, 2024

Uh oh!

dbort left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

facebook-github-bot commented Aug 7, 2024

Uh oh!

facebook-github-bot commented Aug 7, 2024

Uh oh!

facebook-github-bot commented Aug 7, 2024

Uh oh!

dbort left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

facebook-github-bot commented Aug 9, 2024

Uh oh!

facebook-github-bot commented Aug 9, 2024

Uh oh!

facebook-github-bot commented Aug 13, 2024

Uh oh!

facebook-github-bot commented Aug 13, 2024

Uh oh!

facebook-github-bot commented Aug 13, 2024

Uh oh!

facebook-github-bot commented Aug 14, 2024

Uh oh!

dbort left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Olivia-liu Aug 14, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Olivia-liu commented Aug 2, 2024 •

edited

Loading

pytorch-bot bot commented Aug 2, 2024 •

edited

Loading

Olivia-liu Aug 14, 2024 •

edited

Loading