| Message ID | 20240802155449.3528777-1-mmichels@redhat.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [ovs-dev,RFC] Documentation: Define experimental features. | expand |
| Context | Check | Description |
|---|---|---|
| ovsrobot/apply-robot | success | apply and check: success |
| ovsrobot/github-robot-_Build_and_Test | success | github build: passed |
| ovsrobot/github-robot-_ovn-kubernetes | success | github build: passed |
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 <mmichels@redhat.com> > --- 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
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 <mmichels@redhat.com> > > --- > > 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 > 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..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 + 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.
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> --- Documentation/faq/general.rst | 48 +++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+)