From a709b566bd8ae81a92930cc7e553c297470f1ea2 Mon Sep 17 00:00:00 2001 From: jacob-delgado Date: Wed, 13 Jan 2021 08:51:04 -0700 Subject: [PATCH] Add experimental phase of a feature (#495) --- FEATURE-LIFECYCLE.md | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/FEATURE-LIFECYCLE.md b/FEATURE-LIFECYCLE.md index a26d3412..acbb6c3f 100644 --- a/FEATURE-LIFECYCLE.md +++ b/FEATURE-LIFECYCLE.md @@ -10,43 +10,43 @@ information at [Feature Lifecycle Checklist](FEATURE-LIFECYCLE-CHECKLIST.md). - + - + - + - - + + - + - - + + @@ -87,7 +87,7 @@ Enabled by default - + - + - - + + - + @@ -143,7 +145,8 @@ Because the feature is relatively new, it may have minor bugs. - + - +
Development (pre-alpha)Experimental Alpha Beta Stable
PurposeActive development of a feature, not for use by end users directly.Feature is under active development and user facing APIs may change. Users should deploy experimental features with extreme caution, preferably in non-production environments as experimental versions may require a migration effort. Used to get feedback on a design or feature or see how a tentative design performs, etc. Targeted at developers and expert users. Used to vet a solution in production without committing to it in the long term, to assess its viability, performance, usability, etc. Targeted at all users. Dependable, production hardened
StabilityUnknownMay be buggy. Using the feature may expose bugs. Not active by default. May be buggy. Using the feature may expose bugs. Not active by default. Code is well tested. The feature is safe for production use. Code is well tested and stable. Safe for widespread deployment in production.
SecurityUnknownUsing the feature may have obvious security vulnerabilities. Discovered vulnerabilities will not necessarily be communicated broadly.Using the feature may have obvious security vulnerabilities. Discovered vulnerabilities may not be communicated broadly.Using the feature may have obvious security vulnerabilities. Discovered vulnerabilities may not be communicated broadly. Any discovered security vulnerabilities will be publicly disclosed and patched. Any discovered security vulnerabilities will be publicly disclosed and patched.
PerformanceUnknownPerformance characteristics are unknown. Enabling the experimental feature may adversely affect performance. Performance requirements are assessed as part of design. Performance and scalability are characterized, but may have caveats. Perf (latency/scale) is quantified and documented, with guarantees against regression.
SupportNoneNo guarantees on backward compatibility. The feature may be dropped at any time without notice.No guarantees on backward compatibility. The feature may be removed at any time without notice.No guarantees on backward compatibility. The feature may be removed at any time without notice. The overall feature will not be dropped, though details may change. The feature will appear in released software for many subsequent versions.
CompletenessVariesFeature has limited capabilities. This feature may act as a proof of concept. Some API operations or CLI commands may not be implemented The feature need not have had an API review (an intensive and targeted review of the API, on top of a normal code review) All API operations and CLI commands should be implemented @@ -97,7 +97,7 @@ The API has had a thorough API review and is thought to be complete, though use
DocumentationDev features are hidden in auto-generated reference docs.Experimental features are marked as experimental in auto-generated reference docs or they are not exposed. Alpha features are marked alpha in auto-generated reference docs. Basic documentation describing what the feature does, how to enable it, the restrictions and caveats, and a pointer to the issue or design doc the feature is based on. Complete feature documentation published to istio.io @@ -106,10 +106,12 @@ In addition to the basic alpha-level documentation, beta documentation includes
UpgradeabilityNoneThe schema and semantics of a feature may change in a later software release, without any provision for preserving configuration objects in an existing istio installation -API versions can increment faster than the monthly release cadence and the developer need not maintain multiple versions -Developers should still increment the API version when schema or semantics change in an incompatible wayThe schema and semantics of an experimental feature may change in newer versions without any guarantees of preserving backwards compatibility requiring configuration changes during upgrades. +API versions may increment faster than the monthly release cadence and developers are not required to maintain multiple versions for backwards compatibility. +Developers are encouraged to increment the API version when schema or semantics change in an incompatible wayThe schema and semantics of an alpha feature may change in a later software release, without any provision for preserving configuration objects in an existing istio installation +API versions may increment faster than the monthly release cadence and the developer need not maintain multiple versions +Developers should increment the API version when schema or semantics change in an incompatible way The schema and semantics may change in a later software release When this happens, an upgrade path will be documented In some cases, objects will be automatically converted to the new version @@ -135,7 +137,7 @@ Test code coverage is >= 90%.
ReliabilityNoneThe user should not expect the feature to be reliable may be untested. Because the feature is relatively new, and may lack complete end-to-end tests, enabling the feature via a flag might expose bugs which destabilize Istio (e.g. a bug in a control loop might rapidly create excessive numbers of objects, exhausting API storage). Because the feature has e2e tests, enabling the feature should not create new bugs in unrelated features. Because the feature is relatively new, it may have minor bugs.
SupportNoneThere is no commitment from the Istio community to improve, maintain or complete the feature and +the feature may be dropped entirely in a newer release There is no commitment from Istio to complete the feature The feature may be dropped entirely in a later software release Istio commits to complete the feature, in some form, in a subsequent Stable version @@ -153,7 +156,7 @@ Releases should simultaneously support two consecutive versions (e.g. v1beta1 an
Recommended Use CasesDon'tIn short-lived development or testing environments, geared towards soliciting early feedback from users to shape development efforts. In short-lived development or testing environments, due to complexity of upgradeability and lack of long-term support. In development or testing environments. In production environments as part of an evaluation of the feature in order to provide feedback.