| Message ID | 20240813203308.3913702-1-mmichels@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | [ovs-dev,v2] Documentation: Define experimental features. | expand |
| Context | Check | Description |
|---|---|---|
| ovsrobot/apply-robot | success | apply and check: success |
| ovsrobot/github-robot-_Build_and_Test | fail | github build: failed |
| ovsrobot/github-robot-_ovn-kubernetes | fail | github build: failed |
Hi Mark, this definition looks good to me. Thanks for the clarification on how to document this. Martin. > On 13 Aug 2024, at 22:33, Mark Michelson <mmichels@redhat.com> 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 <mmichels@redhat.com> > --- > v1 -> v2: > * Added follow-up question that answers how features are marked > xperimental. > --- > Documentation/faq/general.rst | 54 +++++++++++++++++++++++++++++++++++ > 1 file changed, 54 insertions(+) > > diff --git a/Documentation/faq/general.rst b/Documentation/faq/general.rst > index 831ca0445..df4952ef5 100644 > --- a/Documentation/faq/general.rst > +++ b/Documentation/faq/general.rst > @@ -119,3 +119,57 @@ 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 > + 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. > + > +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.: > -- > 2.45.2 > > _______________________________________________ > dev mailing list > dev@openvswitch.org > https://mail.openvswitch.org/mailman/listinfo/ovs-dev
diff --git a/Documentation/faq/general.rst b/Documentation/faq/general.rst index 831ca0445..df4952ef5 100644 --- a/Documentation/faq/general.rst +++ b/Documentation/faq/general.rst @@ -119,3 +119,57 @@ 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 + 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. + +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.:
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 <mmichels@redhat.com> --- v1 -> v2: * Added follow-up question that answers how features are marked xperimental. --- Documentation/faq/general.rst | 54 +++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+)