X-Git-Url: http://git.cascardo.eti.br/?p=cascardo%2Fovs.git;a=blobdiff_plain;f=CONTRIBUTING.md;h=6f69cfff0b96b5a01f4e014c5972e57e4e85a499;hp=d48924f266eccaa068f8f87c4b72f82deb921246;hb=HEAD;hpb=93e83e8b8a2735ed1c515e9dddc1d45927ebf754

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d48924f26..6f69cfff0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,11 +24,14 @@ 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.
@@ -157,6 +160,17 @@ Examples of common tags follow.
         the tag himself in response to an email indicating successful
         testing results.
 
+    Tested-at: <URL>
+
+        When a test report is publicly available, this provides a way
+        to reference it.  Typical <URL>s would be build logs from
+        autobuilders or references to mailing list archives.
+
+        Some autobuilders only retain their logs for a limited amount
+        of time.  It is less useful to cite these because they may be
+        dead links for a developer reading the commit message months
+        or years later.
+
     Reported-by: Reporter Name <reporter.name@email.address...>
 
         When a patch fixes a bug reported by some person, please
@@ -201,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
 
@@ -218,6 +240,16 @@ 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
+
 Developer's Certificate of Origin
 ---------------------------------
 
@@ -252,6 +284,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
 --------