X-Git-Url: http://git.cascardo.eti.br/?a=blobdiff_plain;f=CONTRIBUTING.md;h=68442d2480101aca3ea1facb75f618f7ea8f8c27;hb=refs%2Fheads%2Frtnetlink;hp=12cb7dc18e545a4702887e6357c2def66e6ed336;hpb=1b17f053e916d6c2c0483a91ad28607517f1325d;p=cascardo%2Fovs.git

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 12cb7dc18..68442d248 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,18 +24,21 @@ 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:
 
-  - A patch that modifies existing code should be tested with
-    `make check` before submission.
+  - A patch that modifies existing code should be tested with `make
+    check` before submission.  Please see INSTALL.md, under
+    "Self-Tests", for more information.
 
   - A patch that adds or deletes files should also be tested with
     `make distcheck` before submission.
 
   - A patch that modifies Linux kernel code should be at least
     build-tested on various Linux kernel versions before
-    submission.  I suggest versions 2.6.32 and whatever
+    submission.  I suggest versions 3.10 and whatever
     the current latest release version is at the time.
 
   - A patch that modifies the ofproto or vswitchd code should be
@@ -212,6 +215,14 @@ Examples of common tags follow.
 
         Reported-at: http://openvswitch.org/pipermail/dev/2014-June/040952.html
 
+    Submitted-at: <URL>
+
+        If a patch was submitted somewhere other than the Open vSwitch
+        development mailing list, such as a GitHub pull request, this header can
+        be used to reference the source.
+
+        Submitted-at: https://github.com/openvswitch/ovs/pull/92
+
     VMware-BZ: #1234567
     ONF-JIRA: EXT-12345
 
@@ -229,6 +240,27 @@ Examples of common tags follow.
         in old change log entries.  (They are obsolete because they do
         not tell the reader what bug tracker is referred to.)
 
+    Fixes: 63bc9fb1c69f (“packets: Reorder CS_* flags to remove gap.”)
+
+        If you would like to record which commit introduced a bug being fixed,
+        you may do that with a “Fixes” header.  This assists in determining
+        which OVS releases have the bug, so the patch can be applied to all
+        affected versions.  The easiest way to generate the header in the
+        proper format is with this git command:
+
+        git log -1 --pretty=format:"Fixes: %h (\"%s\")" --abbrev=12 COMMIT_REF
+
+    Vulnerability: CVE-2016-2074
+
+        Specifies that the patch fixes or is otherwise related to a
+        security vulnerability with the given CVE identifier.  Other
+        identifiers in public vulnerability databases are also
+        suitable.
+
+        If the vulnerability was reported publicly, then it is also
+        appropriate to cite the URL to the report in a Reported-at
+        tag.  Use a Reported-by tag to acknowledge the reporters.
+
 Developer's Certificate of Origin
 ---------------------------------
 
@@ -263,6 +295,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
 --------
 
@@ -295,6 +358,12 @@ Please follow the style used in the code that you are modifying.  The
 [CodingStyle.md] file describes the coding style used in most of Open
 vSwitch. Use Linux kernel coding style for Linux kernel code.
 
+If your code is non-datapath code, you may use the
+`utilities/checkpatch.py` utility as a quick check for certain commonly
+occuring mistakes (improper leading/trailing whitespace, missing signoffs,
+some improper formatted patch files).  For linux datapath code, it is
+a good idea to use the linux script `checkpatch.pl`.
+
 Example
 -------