[Xen-devel] [RFC PATCH] Feature doc: Added Feature Maturity Lifecycle

[Lars Kurth <lars.kurth.xen@xxxxxxxxx>]

- 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.kurth@xxxxxxxxxxxxxx>
---
 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@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel