Skip to content

api-life-cycle.md

Latest commit

History

History
217 lines (180 loc) · 6.09 KB

api-life-cycle.md

File metadata and controls

217 lines (180 loc) · 6.09 KB
Raw

API Life Cycle and Deprecation Policy

API Life Cycle

name

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.

LanguageCodeDocumentation
Python

Use the executorch.exir._warnings.deprecated decorator.

Use the executorch.exir._warnings.experimental decorator.

Use .. warning:: in the docstrings of deprecated and experimental APIs. See example usage.

C++

Use the ET_DEPRECATED annotation macro. See example usage.

Use the ET_EXPERIMENTAL annotation macro.

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__((deprecated("This API is experimental and may change without notice.")));


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

, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
executorch/docs/source/api-life-cycle.md at main · per/executorch · GitHub
Skip to content
api-life-cycle.md
Latest commit
History
History
217 lines (180 loc) · 6.09 KB
api-life-cycle.md
File metadata and controls
217 lines (180 loc) · 6.09 KB
Raw
API Life Cycle and Deprecation Policy
API Life Cycle
name
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.
LanguageCodeDocumentation
Python

Use the
executorch.exir._warnings.deprecated
decorator.

Use the
executorch.exir._warnings.experimental
decorator.

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

Use the ET_DEPRECATED annotation macro. See example usage.

Use the ET_EXPERIMENTAL annotation macro.

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__((deprecated("This API is experimental and may change without notice.")));

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

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
executorch/docs/source/api-life-cycle.md at main · per/executorch · GitHub
Skip to content
api-life-cycle.md
Latest commit
History
History
217 lines (180 loc) · 6.09 KB
api-life-cycle.md
File metadata and controls
217 lines (180 loc) · 6.09 KB
Raw
API Life Cycle and Deprecation Policy
API Life Cycle
name
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.
LanguageCodeDocumentation
Python

Use the
executorch.exir._warnings.deprecated
decorator.

Use the
executorch.exir._warnings.experimental
decorator.

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

Use the ET_DEPRECATED annotation macro. See example usage.

Use the ET_EXPERIMENTAL annotation macro.

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__((deprecated("This API is experimental and may change without notice.")));

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

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
executorch/docs/source/api-life-cycle.md at main · per/executorch · GitHub
Skip to content
api-life-cycle.md
Latest commit
History
History
217 lines (180 loc) · 6.09 KB
api-life-cycle.md
File metadata and controls
217 lines (180 loc) · 6.09 KB
Raw
API Life Cycle and Deprecation Policy
API Life Cycle
name
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.
LanguageCodeDocumentation
Python

Use the
executorch.exir._warnings.deprecated
decorator.

Use the
executorch.exir._warnings.experimental
decorator.

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

Use the ET_DEPRECATED annotation macro. See example usage.

Use the ET_EXPERIMENTAL annotation macro.

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__((deprecated("This API is experimental and may change without notice.")));

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

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
executorch/docs/source/api-life-cycle.md at main · per/executorch · GitHub
Skip to content
api-life-cycle.md
Latest commit
History
History
217 lines (180 loc) · 6.09 KB
api-life-cycle.md
File metadata and controls
217 lines (180 loc) · 6.09 KB
Raw
API Life Cycle and Deprecation Policy
API Life Cycle
name
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.
LanguageCodeDocumentation
Python

Use the
executorch.exir._warnings.deprecated
decorator.

Use the
executorch.exir._warnings.experimental
decorator.

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

Use the ET_DEPRECATED annotation macro. See example usage.

Use the ET_EXPERIMENTAL annotation macro.

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__((deprecated("This API is experimental and may change without notice.")));

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

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
executorch/docs/source/api-life-cycle.md at main · per/executorch · GitHub
Skip to content
api-life-cycle.md
Latest commit
History
History
217 lines (180 loc) · 6.09 KB
api-life-cycle.md
File metadata and controls
217 lines (180 loc) · 6.09 KB
Raw
API Life Cycle and Deprecation Policy
API Life Cycle
name
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.
LanguageCodeDocumentation
Python

Use the
executorch.exir._warnings.deprecated
decorator.

Use the
executorch.exir._warnings.experimental
decorator.

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

Use the ET_DEPRECATED annotation macro. See example usage.

Use the ET_EXPERIMENTAL annotation macro.

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__((deprecated("This API is experimental and may change without notice.")));

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

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
executorch/docs/source/api-life-cycle.md at main · per/executorch · GitHub
Skip to content
api-life-cycle.md
Latest commit
History
History
217 lines (180 loc) · 6.09 KB
api-life-cycle.md
File metadata and controls
217 lines (180 loc) · 6.09 KB
Raw
API Life Cycle and Deprecation Policy
API Life Cycle
name
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.
LanguageCodeDocumentation
Python

Use the
executorch.exir._warnings.deprecated
decorator.

Use the
executorch.exir._warnings.experimental
decorator.

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

Use the ET_DEPRECATED annotation macro. See example usage.

Use the ET_EXPERIMENTAL annotation macro.

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__((deprecated("This API is experimental and may change without notice.")));

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

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
executorch/docs/source/api-life-cycle.md at main · per/executorch · GitHub
Skip to content
api-life-cycle.md
Latest commit
History
History
217 lines (180 loc) · 6.09 KB
api-life-cycle.md
File metadata and controls
217 lines (180 loc) · 6.09 KB
Raw
API Life Cycle and Deprecation Policy
API Life Cycle
name
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.
LanguageCodeDocumentation
Python

Use the
executorch.exir._warnings.deprecated
decorator.

Use the
executorch.exir._warnings.experimental
decorator.

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

Use the ET_DEPRECATED annotation macro. See example usage.

Use the ET_EXPERIMENTAL annotation macro.

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__((deprecated("This API is experimental and may change without notice.")));

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