doc: document feature deprecation and removal process

It seems that we haven't defined clear process on how features should
be removed from OVS.  This patch attempts to document this process.

Signed-off-by: Ansis Atteka <aatteka@nicira.com>
Acked-by: Ben Pfaff <blp@nicira.com>
Acked-by: Flavio Leitner <fbl@sysclose.org>

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 12cb7dc..97ab9cb 100644 (file)
--- 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,37 @@ 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 actually remove the feature from OVS codebase
+once deprecation grace period has expired and users had opportunity to
+use at least one OVS release that would have informed them about feature
+deprecation!
+
 Comments
 --------