openstack/nova
Code Issues Proposed changes

Copy edit feature classification

Browse Source 
Copy edit the feature classification document
to improve language and structure.

blueprint feature-classification

Change-Id: I0ca1f8270439109c3b525b2a22ba3f035f0426f0
This commit is contained in:
Brian Moss 2016-06-01 16:13:48 +10:00 committed by John Garbutt
parent c37af5653c
commit 7ab6397b88
1 changed files with 87 additions and 74 deletions

161
doc/source/feature_classification.rst

@ -15,21 +15,21 @@
Feature Classification Feature Classification
====================== ======================
This document aims to define how we describe features listed in the This document presents a matrix that describes which features are ready to be
:doc:`support-matrix`. used and which features are works in progress. It includes links to relevant
documentation and functional tests.
.. warning:: Please note: this is a work in progress! .. warning:: Please note: this is a work in progress!
Aims Aims
==== ====
Our users want the features they rely on to be reliable and always continue Users want reliable, long-term solutions for their use cases.
to solve for their use case. The feature classification matrix identifies which features are
The feature classification matrix should help identify which features are
complete and ready to use, and which should be used with caution. complete and ready to use, and which should be used with caution.
An additional benefit, is we have a clear list of things where we need help The matrix also benefits developers by providing a list of features that
to complete the feature, its testing and its documentation. require further work to be considered complete.
Below is a matrix for a selection of important verticals: Below is a matrix for a selection of important verticals:
@ -82,48 +82,50 @@ in this set of features.
Notes on Concepts Notes on Concepts
================= =================
Some definitions to help understand the later part of the document. This document uses the following terminology.
Users Users
----- -----
These are the users we will talk about in this document: These are the users we talk about in this document:
* application deployer: creates/deletes servers, directly or indirect via API application deployer
* application developer: creates images and apps that run on the cloud creates and deletes servers, directly or indirectly using an API
* cloud operator: administers the cloud
* self service administrator: both runs and uses the cloud
Now in reality the picture is way more complex. Specifically, there are application developer
likely to be different roles for observer, creator and admin roles for creates images and apps that run on the cloud
the application developer. Similarly, there are likely to be various
levels of cloud operator permissions, some read only, see a subset of
tenants, etc.
Note: this is not attempting to be an exhaustive set of personas that consider cloud operator
various facets of the different users, but instead aims to be a minimal set of administers the cloud
users, such that we use a consistent terminology throughout this document.
self service administrator
runs and uses the cloud
.. note::
This is not an exhaustive list of personas, but rather an indicative set of
users.
Feature Group Feature Group
------------- -------------
To reduce the size of the matrix, we organize the features into groups. To reduce the size of the matrix, we organize the features into groups.
Each group maps to a set of user stories, that can be validated by a set Each group maps to a set of user stories that can be validated by a set
of scenarios, tests. Typically, this means a set of tempest tests. of scenarios and tests. Typically, this means a set of tempest tests.
This list focuses on API concepts like attach and detach volumes, rather This list focuses on API concepts like attach and detach volumes, rather than
than deployment specific concepts like attach iSCSI volume to KVM based VM. deployment specific concepts like attach an iSCSI volume to a KVM based VM.
Deployment Deployment
---------- ----------
A deployment maps to a specific test environment. A full description of the A deployment maps to a specific test environment. We provide a full description
environment should be provided, so its possible to reproduce the test results of the environment, so it is possible to reproduce the reported test results
that are reported for each of the Feature Groups. for each of the Feature Groups.
Note: this description includes all aspects of the deployment: This description includes all aspects of the deployment, for example
the hypervisor, the number of nova-compute services, the storage being used, the hypervisor, number of nova-compute services, storage, network driver,
the network driver being used, the types of images being tested, etc. and types of images being tested.
Feature Group Maturity Feature Group Maturity
----------------------- -----------------------
@ -132,62 +134,73 @@ The Feature Group Maturity rating is specific to the API concepts, rather than
specific to a particular deployment. That detail is covered in the deployment specific to a particular deployment. That detail is covered in the deployment
rating for each feature group. rating for each feature group.
We are starting out these Feature Group ratings: .. note::
* Incomplete Although having some similarities, this list is not directly related
* Experimental to the DefCore effort.
* Complete
* Complete and Required
* Deprecated (scheduled to be removed in a future release)
Incomplete features are those that don't have enough functionality to satisfy **Feature Group ratings:**
real world use cases.
Experimental features should be used with extreme caution. Incomplete
They are likely to have little or no upstream testing. Incomplete features are those that do not have enough functionality to
With little testing there are likely to be many unknown bugs. satisfy real world use cases.
For a feature to be considered complete, we must have: Experimental
Experimental features should be used with extreme caution. They are likely
to have little or no upstream testing, and are therefore likely to
contain bugs.
* Complete API docs (concept and REST call definition) Complete
* Complete Administrator docs For a feature to be considered complete, it must have:
* Tempest tests that define if the feature works correctly
* Has enough functionality, and works reliably enough to be useful
in real world scenarios
* Unlikely to ever have a reason to drop support for the feature
There are various reasons why a feature, once complete, becomes required, but * complete API docs (concept and REST call definition)
currently its largely when a feature is supported by all drivers. Note that * complete Administrator docs
any new drivers need to prove they support all required features before it * tempest tests that define if the feature works correctly
would be allowed in upstream Nova. * sufficient functionality and reliability to be useful in real world
Please note that this list is technically unrelated to the DefCore scenarios
effort, despite there being obvious parallels that could be drawn. * a reasonable expectation that the feature will be supported long-term
Required features are those that any new technology must support before Complete and Required
being allowed into tree. The larger the list, the more features can be There are various reasons why a complete feature may be required, but
expected to be available on all Nova based clouds. generally it is when all drivers support that feature. New
drivers need to prove they support all required features before they are
allowed in upstream Nova.
Deprecated features are those that are scheduled to be removed in a future Required features are those that any new technology must support before
major release of Nova. If a feature is marked as complete, it should being allowed into tree. The larger the list, the more features are
never be deprecated. available on all Nova based clouds.
If a feature is incomplete or experimental for several releases,
it runs the risk of being deprecated, and later removed from the code base. Deprecated
Deprecated features are those that are scheduled to be removed in a future
major release of Nova. If a feature is marked as complete, it should
never be deprecated.
If a feature is incomplete or experimental for several releases,
it runs the risk of being deprecated and later removed from the code base.
Deployment Rating for a Feature Group Deployment Rating for a Feature Group
-------------------------------------- --------------------------------------
The deployment rating is purely about the state of the tests for each The deployment rating refers to the state of the tests for each
Feature Group on a particular deployment. Feature Group on a particular deployment.
There will the following ratings: **Deployment ratings:**
* unknown Unknown
* not implemented No data is available.
* implemented: self declare the tempest tests pass
* regularly tested: tested by third party CI
* checked: Tested as part of the check or gate queue
The eventual goal is to automate this list from some third party CI reporting Not Implemented
system, but so we can make progress, this will be a manual inspection that is No tests exist.
documented by an hand written ini file. Ideally, this will be reviewed every
milestone. Implemented
Self declared that the tempest tests pass.
Regularly Tested
Tested by third party CI.
Checked
Tested as part of the check or gate queue.
The eventual goal is to automate this list from a third party CI reporting
system, but currently we document manual inspections in an ini file.
Ideally, we will review the list at every milestone.