From patchwork Tue Aug 13 20:33:03 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mark Michelson X-Patchwork-Id: 1972101 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=HhVexZ6u; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=openvswitch.org (client-ip=2605:bc80:3010::138; helo=smtp1.osuosl.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=patchwork.ozlabs.org) Received: from smtp1.osuosl.org (smtp1.osuosl.org [IPv6:2605:bc80:3010::138]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4Wk34K74svz1yXl for ; Wed, 14 Aug 2024 06:33:20 +1000 (AEST) Received: from localhost (localhost [127.0.0.1]) by smtp1.osuosl.org (Postfix) with ESMTP id C6F65812E1; Tue, 13 Aug 2024 20:33:17 +0000 (UTC) X-Virus-Scanned: amavis at osuosl.org Received: from smtp1.osuosl.org ([127.0.0.1]) by localhost (smtp1.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP id mT9bnd9TIorW; Tue, 13 Aug 2024 20:33:16 +0000 (UTC) X-Comment: SPF check N/A for local connections - client-ip=2605:bc80:3010:104::8cd3:938; helo=lists.linuxfoundation.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver= DKIM-Filter: OpenDKIM Filter v2.11.0 smtp1.osuosl.org ACBCA8120C Authentication-Results: smtp1.osuosl.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=HhVexZ6u Received: from lists.linuxfoundation.org (lf-lists.osuosl.org [IPv6:2605:bc80:3010:104::8cd3:938]) by smtp1.osuosl.org (Postfix) with ESMTPS id ACBCA8120C; Tue, 13 Aug 2024 20:33:16 +0000 (UTC) Received: from lf-lists.osuosl.org (localhost [127.0.0.1]) by lists.linuxfoundation.org (Postfix) with ESMTP id 885E4C0A97; Tue, 13 Aug 2024 20:33:16 +0000 (UTC) X-Original-To: dev@openvswitch.org Delivered-To: ovs-dev@lists.linuxfoundation.org Received: from smtp1.osuosl.org (smtp1.osuosl.org [140.211.166.138]) by lists.linuxfoundation.org (Postfix) with ESMTP id 44E28C0A96 for ; Tue, 13 Aug 2024 20:33:15 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by smtp1.osuosl.org (Postfix) with ESMTP id 3F00081220 for ; Tue, 13 Aug 2024 20:33:15 +0000 (UTC) X-Virus-Scanned: amavis at osuosl.org Received: from smtp1.osuosl.org ([127.0.0.1]) by localhost (smtp1.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP id REIWGEDpC9FU for ; Tue, 13 Aug 2024 20:33:14 +0000 (UTC) Received-SPF: Pass (mailfrom) identity=mailfrom; client-ip=170.10.129.124; helo=us-smtp-delivery-124.mimecast.com; envelope-from=mmichels@redhat.com; receiver= DMARC-Filter: OpenDMARC Filter v1.4.2 smtp1.osuosl.org 3E0878120C Authentication-Results: smtp1.osuosl.org; dmarc=pass (p=none dis=none) header.from=redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 smtp1.osuosl.org 3E0878120C Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by smtp1.osuosl.org (Postfix) with ESMTPS id 3E0878120C for ; Tue, 13 Aug 2024 20:33:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1723581192; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=n7hXNlZaWD7Vdej/nuzP/lRXHBsMKoLLdJBtMg1Zb3k=; b=HhVexZ6uLX0tLy6+Gjkun/llwvJ12/cauak0yOzmICvXkrG7VO09rAzHl7eLH+ZmCB/NiP WQGEsNHIPfAhN/8PUWIM3ya3uLEzLJhqMmsWoSfLvSBEJJ/ud3qljS03EB6b5GMs7UkFwL qBtcG5z0fqk+XW8XJCv7anUI1jeud18= Received: from mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-625-1IDKPmAUO_SHWAGJZ0IbBw-1; Tue, 13 Aug 2024 16:33:11 -0400 X-MC-Unique: 1IDKPmAUO_SHWAGJZ0IbBw-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id A8A0B1956048 for ; Tue, 13 Aug 2024 20:33:10 +0000 (UTC) Received: from localhost.redhat.com (ovpn-0-3.rdu2.redhat.com [10.22.0.3]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 08F6C1955F40 for ; Tue, 13 Aug 2024 20:33:09 +0000 (UTC) From: Mark Michelson To: dev@openvswitch.org Date: Tue, 13 Aug 2024 16:33:03 -0400 Message-ID: <20240813203308.3913702-1-mmichels@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Subject: [ovs-dev] [PATCH ovn v2] Documentation: Define experimental features. X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: ovs-dev-bounces@openvswitch.org Sender: "dev" 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 --- 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 `. + +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.: