Hi Mark and Dumitru, On Tue, 2024-08-06 at 15:19 +0200, Dumitru Ceara wrote: > 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. >
I like the idea of keeping the "experimental" tag in place with the rest of the documentation feature (i.e. directly in the man page files). It makes it immediately visible to the user that some feature is experimental and it also keeps it in spotlight of developers when working on the feature (e.g. when it's time to remove the tag). > 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 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
