- Incorporated feedback from http://lists.xenproject.org/archives/html/xen-devel/2015-06/msg01992.html
Open Issues: - Did not build and test the doc yet (want to get the content right first) - Decide on supported status in MAINTAINER file - Resolve loose ends on where and how to record Feature State Signed-off-by: Lars Kurth <lars.ku...@xenproject.org> --- docs/features/feature-maturity-lifecycle.pandoc | 260 ++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 docs/features/feature-maturity-lifecycle.pandoc diff --git a/docs/features/feature-maturity-lifecycle.pandoc b/docs/features/feature-maturity-lifecycle.pandoc new file mode 100644 index 0000000..46f98a7 --- /dev/null +++ b/docs/features/feature-maturity-lifecycle.pandoc @@ -0,0 +1,260 @@ +% Feature Maturity Lifecycle +% Revision 1 + +\clearpage + +# Basics +--------------- ------------------- + Status: **Proposal** + + Component: Development Process +--------------- ------------------- + +# Purpose and Scope + +The purpose of this document is to define the possible states a feature. +**Features** may be one of the following: +* End user Feature: aka a pice of functionality that is controllable + by users of Xen through a command line option exposed via xl or + libvirt, a config file or otherwise +* Support for a Hardware platform: e.g. x86 or ARM +* Support for a specific Hardware platforms, e.g. Thunder X, + Xilinx ZynqMP, etc. +* A set of APIs, e.g. mem-event API, memory sharing APIs, etc. + +It is also the intent, that this document is used to set expectations +of contributors to the Xen Project hypervisor, such that they can take +appropriate steps to ensure that eventually a feature that they develop +is a supported by the community. + +Further, it will help users of the Xen Project hypervisors understand +how developers use the feature states. This will help users make informed +decisions about the risk involved in using a feature. + +# Dependencies + +This document refers to definitions in other files and project conventions, +in particular: + +## Status of subsystems in the MAINTAINERS file +The [MAINTAINERS] +(http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=MAINTAINERS;hb=HEAD) +file maps individuals against groups of files in the source tree. In +the context of this document, we say that a feature is **maintained**, +iff all components of that feature are marked as one of the following +* **Supported**: Someone is actually paid to look after the code. +* **Maintained**: Someone actually looks after the code. + +## Classification of public APIs and interfaces: +APIs and other interfaces are declared stable by agreement +on the xen-devel@ mailing list. We consider a feature as +**stable**, iff all public APIs and interfaces a feature depends +on have been declared stable. + +## Testing +The Xen Project runs a continuous test and integration system +in the project's test lab. We consider a **feature tested**, iff +one of the following two criteria holds: +* The feature is tested automatically +* At least once during each release freeze, the feature's + maintainers produce a test report (by a deadline specified by + the release manager). Features with no test report get + downgraded from **Supported** to some lower status. + +For hardware platforms we consider a **platform tested**, iff +* Appropriate hardware for said platform is live and in active use + in our test lab and tests consistently pass against that platform. +* At least once during each release freeze, the hardware platform's + maintainers produce a test report (by a deadline specified by + the release manager). Hardware Platforms with no test report get + downgraded from **Supported** to some lower status. + +## Documentation +The Xen Project requires that documentation for user facing +features and in-code API documentation (or user guides as +appropriate) are provided in tree. + +For new larger features, we do also expect that feature documentation +is submitted to [xen.git / docs / features] +(http://xenbits.xen.org/gitweb/?p=xen.git;a=tree;f=docs/features;hb=HEAD). +Whether such documentation is required depends on the discretion of +the maintainers and committers that review new features. + +We say that a feature as **documented**, if relevant documentation has +been committed to the tree. + +# State Definitions + +This section lists state definitions of a **Feature** in terms of +properties. This section talks about Features, for readability, but +is used interchangeably between **Features** and **Platforms**. + +States are listed in order of increasing number +of properties. Note that note all features will require to go +through each state: for example small and non-risky features +may go straight from under development to supported. It is up to +the development community to judge and discuss, which states +are necessary based on the size and risk of a feature. + +## Preview +* Partially completed, with missing functionality +* May **not be fully functional** in all cases +* May **not be tested** +* APIs and interfaces may **not be stable** +* The developer is actively looking for user feedback +* Bugs and issues can be raised on xen-devel@ and will be + handled on a best-effort basis + +## Experimental +* Core functionality is **fully functional** +* However, not all functionality or platform support may be + present +* May **not be tested**, although there is an expectation that a plan + to improve testing is in place or worked on +* APIs and interfaces may **not be stable** +* Bugs and issues can be raised on xen-devel@ and will be + handled on a best-effort basis. However, there is an expectation + that issues related to broken core functionality are addressed. + +## Complete +This is a state which has not existed in the past. It is aimed +at larger new features, which may only be in use or of interest +to a small number of contributors, or where not enough expertise +exists in the community to treat the feature as **Supported**. It +presents an opportunity for developers to prove over one or +two release cycles that said feature can be **supported** in future. + +* Intended functionality is **fully implemented** +* Feature is **maintained** +* Feature is **tested** +* Feature is **stable** +* Feature is **documented** +* Bugs and issues can be raised on xen-devel@ and will be + handled by the developers/maintainers behind the feature. There + is an expectation for the developers/maintainers to address + bugs and issues over a period of time. +* Regressions and blockers in a complete feature do **not** normally + block new releases. It is at the discretion of the community + and Release Manager to downgrade the feature. + Security issues would **not** be handled by the security team. + +## Supported +* Intended functionality is **fully implemented** +* Feature is **maintained** +* Feature is **tested** +* Feature is **stable** +* Feature is **documented** +* Bugs and issues can be raised on xen-devel@ and will be + handled by the developers/maintainers/committers within the + community. +* Regressions and blockers in a complete feature do normally + block new releases. +* Security issues would be handled by the security team. + + +## Supported-Legacy-Stable +According to this classification, a lot of our existing features would +have to move back to **Experimental** until have tested and documented +them. In other words, the following criteria may not always hold for +such features: + +* Feature is **tested** +* Feature is **documented** + +However many of these features and platforms are known to work in +production. For this reason, such features will be marked as +**Supported-Legacy-Stable** to ease migration to the new **Supported** +criteria. **Supported-Legacy-Stable** fulfils the following criteria: + +* Intended functionality is **fully implemented** +* Feature is **maintained** +* Feature is **stable** +* Bugs and issues can be raised on xen-devel@ and will be + handled by the developers/maintainers/committers within the + community. +* Regressions and blockers in a complete feature do normally + block new releases. +* Security issues would be handled by the security team. + +## Deprecated +There are typically two scenarios when a feature would be +deprecated. +* If the feature is not relevant any more or has been replaced + by a new implementation (e.g. xm vs. xl) +* If we have lost the capability to support a feature. + For example when we have lost the capability to **maintain** + the feature, because we do not have maintainers. In such cases + raising the issue on xen-devel@ usually will lead to a resolution, + if there is enough usage by vendors in the eco-system. + +Features in any state can be deprecated. + +The following properties apply to deprecated features: +* Bugs and issues can be raised on xen-devel@ and will be + handled at the discretion of the community. +* Regressions and blockers in a deprecated feature do normally + block new releases. +* Security issues for deprecated features are handled by the security + team at their discretion. + +# Recording Feature Maturity Status + +## State Recording Prior to the introduction of the Feature Maturity Lifecycle + +Prior to the introduction of this document, Feature Maturity was listed in +[Xen Project Release Features] +(http://wiki.xenproject.org/wiki/Xen_Project_Release_Features). + +## State Recording + +The intention here is to require that the central file is modified +with a patch that introduces a feature (state, feature title, +short description) and that developers which add functionality +modify accordingly. The release manager and other stake-holders +such as the community may also propose changes during the release +cycle (in particular towards the end). + +TODO: Sort out the detail. I would propose 3 files, covering *Platforms*, +*Limits* and *Features*, assuming that their requirements are different. +One of the open questions is whether duplicating information in files +such as migration.pandoc and one of the new files would be an issue. If it +is, then we probably need to write a script, which scrapes information from +files and generates some info. + +# Downgrading Feature Maturity +If a feature has been for too long on in an incomplete state (e.g. +**Preview** or **Experimental**) or some of the assumptions associated +with a state do not hold any more, community members may propose to +downgrade a feature on xen-devel@. Typically a discussion on +the list would be expected before a patch to the file is proposed. + +# Known Issues + +## Supported status in MAINTAINERS +One comment raised in this [e-mail] +(http://lists.xenproject.org/archives/html/xen-devel/2015-06/msg02140.html), +was that we should rename the `Supported' field in [MAINTAINERS] +(http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=MAINTAINERS;hb=HEAD) +to avoid confusion. For now, I do not want to block the proposal and instead just make a note, such that we can address this later. + +## Table of Legacy Supported Features +We need to finalise the format and location for information covering *Platforms*, *Limits* and *Features* and then update section +**State Recording** accordingly. + +# References + +* For an earlier discussion leading to this document, see this + [e-mail thread] + (http://lists.xenproject.org/archives/html/xen-devel/2015-06/msg01992.html). + +* Historical Feature support Status can be found in + [Xen Project Release Features] + (http://wiki.xenproject.org/wiki/Xen_Project_Release_Features) + +# History + +------------------------------------------------------------------------ +Date Revision Version Notes +---------- -------- -------- ------------------------------------------- +2015-11-06 1 Xen 4.7 Document written +---------- -------- -------- ------------------------------------------- -- 2.1.4 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xen.org http://lists.xen.org/xen-devel