netdev-dpdk: fix mbuf leaks

[cascardo/ovs.git] / CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b434e78..6f69cff 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,10 +24,16 @@ In particular:
 
   - A patch that adds or removes user-visible features should
     also update the appropriate user documentation or manpages.
 
   - 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:
 
 
 Testing is also important:
 

-  - A patch that adds or deletes files should be tested with
+  - 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
     `make distcheck` before submission.
 
   - A patch that modifies Linux kernel code should be at least


@@ -44,8 +50,8 @@ Testing is also important:
 If you are using GitHub, then you may utilize the travis-ci.org CI build
 system by linking your GitHub repository to it. This will run some of
 the above tests automatically when you push changes to your repository.
 If you are using GitHub, then you may utilize the travis-ci.org CI build
 system by linking your GitHub repository to it. This will run some of
 the above tests automatically when you push changes to your repository.

-See the "Continuous Integration with Travis-CI" in the [INSTALL](INSTALL.md)
-file for details on how to set it up.
+See the "Continuous Integration with Travis-CI" in the [INSTALL.md] file
+for details on how to set it up.

 
 Email Subject
 -------------
 
 Email Subject
 -------------


@@ -154,6 +160,17 @@ Examples of common tags follow.
         the tag himself in response to an email indicating successful
         testing results.
 
         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
     Reported-by: Reporter Name <reporter.name@email.address...>
 
         When a patch fixes a bug reported by some person, please


@@ -198,6 +215,14 @@ Examples of common tags follow.
 
         Reported-at: http://openvswitch.org/pipermail/dev/2014-June/040952.html
 
 
         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
 
     VMware-BZ: #1234567
     ONF-JIRA: EXT-12345
 


@@ -215,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.)
 
         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
 ---------------------------------
 
 Developer's Certificate of Origin
 ---------------------------------
 


@@ -249,6 +284,37 @@ certifies the following:
         maintained indefinitely and may be redistributed consistent with
         this project or the open source license(s) involved.
 
         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
 --------
 
 Comments
 --------
 


@@ -278,8 +344,8 @@ If you cannot convince your email client not to mangle patches, then
 sending the patch as an attachment is a second choice.
 
 Please follow the style used in the code that you are modifying.  The
 sending the patch as an attachment is a second choice.
 
 Please follow the style used in the code that you are modifying.  The

-[CodingStyle](CodingStyle.md) file describes the coding style used in
-most of Open vSwitch. Use Linux kernel coding style for Linux kernel code.
+[CodingStyle.md] file describes the coding style used in most of Open
+vSwitch. Use Linux kernel coding style for Linux kernel code.

 
 Example
 -------
 
 Example
 -------


@@ -316,3 +382,5 @@ index fdd952e..f6cb88e 100644
 1.7.7.3
 ```
 
 1.7.7.3
 ```
 

+[INSTALL.md]:INSTALL.md
+[CodingStyle.md]:CodingStyle.md