From patchwork Sat Sep 19 20:22:39 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ansis Atteka X-Patchwork-Id: 519776 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from archives.nicira.com (unknown [IPv6:2600:3c00::f03c:91ff:fe6e:bdf7]) by ozlabs.org (Postfix) with ESMTP id 8A5411401DE for ; Sun, 20 Sep 2015 06:22:53 +1000 (AEST) Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id 3F30E10CA6; Sat, 19 Sep 2015 13:22:52 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx3v1.cudamail.com (mx3.cudamail.com [64.34.241.5]) by archives.nicira.com (Postfix) with ESMTPS id B1A6510CA5 for ; Sat, 19 Sep 2015 13:22:51 -0700 (PDT) Received: from bar4.cudamail.com (bar2 [192.168.15.2]) by mx3v1.cudamail.com (Postfix) with ESMTP id E06486193FB for ; Sat, 19 Sep 2015 14:22:50 -0600 (MDT) X-ASG-Debug-ID: 1442694168-03dc216c1a014b0001-byXFYA Received: from mx3-pf1.cudamail.com ([192.168.14.2]) by bar4.cudamail.com with ESMTP id IwyZEKlpY4097YFS (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sat, 19 Sep 2015 14:22:48 -0600 (MDT) X-Barracuda-Envelope-From: aatteka@nicira.com X-Barracuda-RBL-Trusted-Forwarder: 192.168.14.2 Received: from unknown (HELO mail-pa0-f44.google.com) (209.85.220.44) by mx3-pf1.cudamail.com with ESMTPS (RC4-SHA encrypted); 19 Sep 2015 20:22:48 -0000 Received-SPF: unknown (mx3-pf1.cudamail.com: Multiple SPF records returned) X-Barracuda-RBL-Trusted-Forwarder: 209.85.220.44 Received: by pacex6 with SMTP id ex6so80129948pac.0 for ; Sat, 19 Sep 2015 13:22:48 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=knACwbgxRF7gcXjkZM021Llrs1ygwNRuFJN5tm1YskU=; b=TTwUbCW/DT7KBXppXKZ/Fq108+vOaq1RIDStDXDw5VZl2eUjZsnshjvgv//hFNMIGo ng/HXms2jC01mtvZVY45FeGKZcTCwTY7f6NCR3QOZSqflB7aJEk3gbCqzH+CQ8nt40LO zljvy86pSjHNpGNwnRwB8GIx7Y2rLlv7jHulZ2KjIVRiz/gowvntv6Yb/6dP5Bhl+in7 1sswCtSVn7Vj/ZTKkxnPUrXZuG5MAb2TJpxFhf7j1nC4KtL0PoMDpsO3n+X7j2a0lOcQ CiQA7HS9PF6njcnmH1HpVn0Rug+2KoBRiOS5vnp9Lhbloe5S42FuVX8DxC05qhPnRRi/ BWtg== X-Gm-Message-State: ALoCoQn0kXgZtp4r5S+JDqJFDFy5XzY4aIDbtzd1i6Pv/dpDN8IZSDUro96n1lwMC+Y8ia9aonD5 X-Received: by 10.66.142.233 with SMTP id rz9mr14559241pab.23.1442694168121; Sat, 19 Sep 2015 13:22:48 -0700 (PDT) Received: from aatteka-MacBookPro.eng.vmware.com ([208.91.1.34]) by smtp.gmail.com with ESMTPSA id am4sm15929893pbd.58.2015.09.19.13.22.47 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sat, 19 Sep 2015 13:22:47 -0700 (PDT) X-CudaMail-Envelope-Sender: aatteka@nicira.com X-Barracuda-Apparent-Source-IP: 208.91.1.34 From: Ansis Atteka To: dev@openvswitch.org X-CudaMail-Whitelist-To: dev@openvswitch.org X-CudaMail-MID: CM-V1-918022069 X-CudaMail-DTE: 091915 X-CudaMail-Originating-IP: 209.85.220.44 Date: Sat, 19 Sep 2015 13:22:39 -0700 X-ASG-Orig-Subj: [##CM-V1-918022069##][PATCH] doc: document feature deprecation and removal process Message-Id: <1442694159-4809-1-git-send-email-aatteka@nicira.com> X-Mailer: git-send-email 2.1.4 X-Barracuda-Connect: UNKNOWN[192.168.14.2] X-Barracuda-Start-Time: 1442694168 X-Barracuda-Encrypted: DHE-RSA-AES256-SHA X-Barracuda-URL: https://web.cudamail.com:443/cgi-mod/mark.cgi X-ASG-Whitelist: Header =?UTF-8?B?eFwtY3VkYW1haWxcLXdoaXRlbGlzdFwtdG8=?= X-Virus-Scanned: by bsmtpd at cudamail.com X-Barracuda-BRTS-Status: 1 Subject: [ovs-dev] [PATCH] doc: document feature deprecation and removal process X-BeenThere: dev@openvswitch.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dev-bounces@openvswitch.org Sender: "dev" It seems that we haven't defined clear process on how features should be removed from OVS. This patch attempts to document this process. Singed-off-by: Ansis Atteka Acked-by: Ben Pfaff Acked-by: Flavio Leitner --- CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12cb7dc..12d2a77 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,8 @@ In particular: - A patch that adds or removes user-visible features should also update the appropriate user documentation or manpages. + Check "Feature Deprecation Guidelines" section in this document + if you intend to remove user-visible feature. Testing is also important: @@ -263,6 +265,35 @@ certifies the following: maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. +Feature Deprecation Guidelines +------------------------------ + +Open vSwitch is intended to be user friendly. This means that under +normal circumstances we don't abruptly remove features from OVS that +some users might still be using. Otherwise, if we would, then we would +possibly break our user setup when they upgrade and would receive bug +reports. + +Typical process to deprecate a feature in Open vSwitch is to: + + (a) Mention deprecation of a feature in the NEWS file. Also, mention + expected release or absolute time when this feature would be removed + from OVS altogether. Don't use relative time (e.g. "in 6 months") + because that is not clearly interpretable. + + (b) If Open vSwitch is configured to use deprecated feature it should print + a warning message to the log files clearly indicating that feature is + deprecated and that use of it should be avoided. + + (c) If this feature is mentioned in man pages, then add "Deprecated" keyword + to it. + +Also, if there is alternative feature to the one that is about to be marked +as deprecated, then mention it in (a), (b) and (c) as well. + +Remember to followup and acctually remove the feature from OVS codebase +once deprecation grace period has expired! + Comments --------