On 9/19/24 11:25, Numan Siddique wrote:
On Wed, Aug 14, 2024 at 5:20 AM Martin Kalcok
<[email protected]> wrote:
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 <[email protected]> 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]>
---
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.:
Acked-by: Numan Siddique <[email protected]>
Numan
I merged this to main.
--
2.45.2
_______________________________________________
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
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
