On 8/2/24 17:54, Mark Michelson wrote: > During a recent OVN community call, it was questioned what it means for > a feature to be marked experimental. This documentation change aims to > clarify what it means when a feature is marked experimental. > > Signed-off-by: Mark Michelson <[email protected]> > ---
Hi Mark, > Documentation/faq/general.rst | 48 +++++++++++++++++++++++++++++++++++ > 1 file changed, 48 insertions(+) > > diff --git a/Documentation/faq/general.rst b/Documentation/faq/general.rst > index 831ca0445..a6292acd0 100644 > --- a/Documentation/faq/general.rst > +++ b/Documentation/faq/general.rst > @@ -119,3 +119,51 @@ Q: How can I contribute to the OVN Community? > questions. You can also suggest improvements to documentation. If you > have a feature or bug you would like to work on, send a mail to one of > the > :doc:`mailing lists </internals/mailing-lists>`. > + > +Q: What does it mean when a feature is marked "experimental"? > + > + A: Experimental features are marked this way because of one of I think one thing that's missing is a reference to how features are marked "experimental". I guess one way is to mark them "experimental" in the NEWS file and then later, when they become "stable" there's going to be a new entry that mentions that. Maybe a better way would be to actually add a standard way of doing that in the corresponding man page? E.g., what if we add another question here: Q: How is a feature marked "experimental"? A: Experimental features must contain the following note in their man pages (ovn-nb.5, ovn-sb.5, ovn-controller.8, etc): "NOTE: this feature is experimental and may be subject to removal/change in the future.". Or would it make sense to maintain an EXPERIMENTAL_FEATURES.rst file (similar to TODO.rst)? Although TODO.rst is probably still not up to date. The rest of the patch looks good to me! > + several reasons: > + > + * The developer was only able to test the feature in a limited > + environment. Therefore the feature may not always work as intended > + in all environments. > + > + * During review, the potential for failure was noticed, but the > + circumstances that would lead to that failure were hard to nail > + down or were strictly theoretical. > + > + * What exists in OVN may be an early version of a more fleshed-out > + feature to come in a later version. > + > + * The feature was developed against a draft RFC that is subject to > + change when the RFC is published. > + > + * The feature was developed based on observations of how a specific > + vendor implements a feature, rather than using IETF standards or > + other documentated specifications. > + > + A feature may be declared experimental for other reasons as well, > + but the above are the most common. When a feature is marked > + experimental, it has the following properties: > + > + * The feature must be opt-in. The feature must be disabled by > + default. When the feature is disabled, it must have no bearing > + on other OVN functionality. > + > + * Configuration and implementation details of the feature are > + subject to change between major or minor versions of OVN. > + > + * Users make use of this feature at their own risk. Users are free > + to file issues against the feature, but developers are more likely > + to prioritize work on non-experimental features first. > + > + * Experimental features may be removed. For instance, if an > + experimental feature exposes a security risk, it may be removed > + rather than repaired. > + > + The hope is that experimental features will eventually lose the > + "experimental" marker and become a core feature. However, there is > + no specific test or process defined for when a feature no longer > + needs to be considered experimental. This typically will be decided > + collectively by OVN maintainers. Regards, Dumitru _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
