Open to the idea of a features list?

[sdake]

Hi Gang,

First off, cloud-hypervisor is pretty awesome. Like many open source projects, the documentation could use a bit of a tuneup. The biggest impact feature I can think of that would help people get moving is, strangely, a feature list.

As my first foray into producing a useful contribution to this project, I'd like to do this basic feature list. I assembled this feature list for Istio: https://istio.io/latest/docs/releases/feature-stages/

If one of the maintainers would be so kind as to accept this proposal by assigning this issue to me, I would appreciate it.

Cheers,
-steve

[iggy]

Looks like a good addition. I'd personally put the definitions below the actual list, but I can see it both ways

[sdake]

@iggy right. When I did the original work, there were only a few definitions. Now there are like 20 :) - I think we could start smaller, and tune to our liking.

Cheers,
-steve

[rbradford]

@sdake Sounds good. Looking forward to your contribution!

[sdake]

@weltling Would you be adversely affected if I worked to lift the unstable features and better define the stability guarantees from a few parts excellent release document in PR #3957.

I don't want to duplicate work, although I do want to formalize the feature list in this issue and precisely define the feature maturity as part of that list. I plan to do this as three PRs that can independently review - which can merge into one or merge independently.

• develop feature list documentation
  • Unify PR Release doc #3957 feature information inone place features.md.
  • Formalize a feature maturity model containing a description of the various feature maturities and their associated attributes. Strawman proposal.
  • Produce a feature catalog containing a list of features in this project.
  • Produce a feature maturity catalog containing a mapping of feature to maturity.

For an example of what this looks like taken to the extreme, see the Istio feature stages. I am not a fan of the overly ambitious support model of Istio, but I am a fan of defining for our users exactly what the upstream support model is.

Thank you,
-steve

[sdake]

By trade, I am not a technical writer. However, to learn the codebase and the project, I must undertake some technical writing work, so thank you in advance for tolerating my technical writing expertise.

This proposal is copied and reformatted from a comment I made in the the LTS proposal.

Stage	Description
DEVELOPMENT	The feature is in development, may or may not be usable, and is highly suitable for developer participation.
EXPERIMENTAL	The feature is developed, may not be finalized, and no support guarantees, including API guarantees, are provided.
ALPHA	The feature is ready for evaluation, but the maintainers may remove the feature from a future release.
BETA	The feature is ready for production workloads, and some basic support guarantees are made, such as the feature will not be removed in the N-1 (e.g., last LTS release).
STABLE	The feature is finalized, documented, tested both unit and functional, and guarantees are made about the API and its associated functionality. The maintainers will announce any feature deprecation with a timeline for removal, e.g., LTS+1 or LTS+2.
DEPRECATED	The feature was previously a BETA or STABLE feature but was deprecated and is now part of the historical bit bucket. The maintainers record the deprecation declaration and deprecation application

When we undertook this work in Istio, the Initail Istio Feature Stages held significant community interest. Unfortunately, the latest version of the Istio feature stages was rebased improperly, resulting in lost commit history, groan, but shows how this work could evolve if we so choose.

Thank you,
-steve

[rbradford]

@sdake You should also look at https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/device_model.md for more inspiration (it's somewhat out of date though.)

[sdake]

@rbradford,

Thank you. I have read and read the docs directory as well as reading the src code, especially config.rs, I have plenty of notes, and working on organizing them into a PR, definitely today.

One thing that is undocumented, and I am not sure if it is intentional or not, are the perf and scale expected behaviors. I would have liked to see the performance (memory, CPU, network) with vhost user net - i.e., https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/vhost-user-net-testing.md

I have found https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/performance_metrics.md of course, but I rather test the bring-up with the howtos.

If you have suggestions here, welcome to hear em. :)

Cheers,
-steve

[rbradford]

@sdake The performance you get with vhost-user-net is highly dependent on how you configure that backend you talk to with it. DPDK is the most common one and has a huge number of options for configuring it including using userspace drivers for the network interface. As the VMM we don't really provide recommendations on how the customer can use the code.

[sdake]

@rbradford thanks, I will not add scale and perf to the feature list. Also thank you for the keyword backend - so obvious. Still, and forever, learning.

Cheers,
-steve

[weltling]

@sdake thanks for looking into this effort. Yes, a reified commitment to stability was one of the goals in the release doc discussion. With regard to the features also - connecting feature stability to the release cycle would be a promise definition to be given to the consumer.

With the table listing the stage terminology of dev, alpha, beta and so on - i would know it more related to the release cycle as that's where it's applied to the versioning to indicate stablity. An alpha release would refer to the product version as a whole. Nevertheless, the idea of defining features stability separately could be applicable, too.

Perhaps this should be conditioned by the fact that the default features (eg. cargo build) would need to be always stable. Perhaps some selectors could be implemented to say "enable all alpha features" or similar. Otherwise, say modifying a default feature list to add a single experimental feature could be a way to go, too. In the case of the table, perhaps a table of the features would need to be updated for every release, in that case one wolud think on how to ease that to be done automatically. Having a detailed statement on the feature stability would be IMO profitable for the user to increase the project transparency.

Thanks