Submitting Patches
Send changes to OVN as patches to dev@openvswitch.org. One patch per email. More details are included below.
If you are using Git, then git format-patch takes care of most of the mechanics described below for you.
Before You Start
Before you send patches at all, make sure that each patch makes sense. In particular:
A given patch should not break anything, even if later patches fix the problems that it causes. The source tree should still build and work after each patch is applied. (This enables git bisect to work best.)
A patch should make one logical change. Don’t make multiple, logically unconnected changes to disparate subsystems in a single patch.
A patch that adds or removes user-visible features should also update the appropriate user documentation or manpages. Consider adding an item to NEWS for nontrivial changes. Check “Feature Deprecation Guidelines” section in this document if you intend to remove user-visible feature.
Testing is also important:
Test a patch that modifies existing code with
make check
before submission. Refer to the “Unit Tests” in Testing, for more information. We also encourage running the kernel and userspace system tests.Consider testing a patch that adds or deletes files 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 3.10 and whatever the current latest release version is at the time.
A patch that adds a new feature should add appropriate tests for the feature. A bug fix patch should preferably add a test that would fail if the bug recurs.
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 Testing for details on how to set it up.
Email Subject
The subject line of your email should be in the following format:
[PATCH ovn <n>/<m>] <area>: <summary>
Where:
[PATCH ovn]
:indicates that this is the patch and it is targeted for OVN project. This is important since OVN and OVS are using same mailing lists for development.
ovn
word could be added manually or by usinggit format-patch --subject-prefix="PATCH ovn" ...
. It might be useful to add following configuration to a local.git/config
:[format] subjectPrefix = "PATCH ovn"
<n>/<m>
:indicates that this is the nth of a series of m patches. It helps reviewers to read patches in the correct order. You may omit this prefix if you are sending only one patch.
<area>
:indicates the area of OVN to which the change applies (often the name of a source file or a directory). You may omit it if the change crosses multiple distinct pieces of code.
<summary>
:briefly describes the change. Use the imperative form, e.g. “Force SNAT for multiple gateway routers.” or “Fix daemon exit for bad datapaths or flows.” Try to keep the summary short, about 50 characters wide.
The subject, minus the [PATCH ovn <n>/<m>]
prefix, becomes the first line
of the commit’s change log message.
Description
The body of the email should start with a more thorough description of the change. This becomes the body of the commit message, following the subject. There is no need to duplicate the summary given in the subject.
Please limit lines in the description to 75 characters in width. That allows the description to format properly even when indented (e.g. by “git log” or in email quotations).
The description should include:
The rationale for the change.
Design description and rationale (but this might be better added as code comments).
Testing that you performed (or testing that should be done but you could not for whatever reason).
Tags (see below).
There is no need to describe what the patch actually changed, if the reader can see it for himself.
If the patch refers to a commit already in the OVN repository, please include both the commit number and the subject of the patch, e.g. ‘commit 632d136c (vswitch: Remove restriction on datapath names.)’.
If you, the person sending the patch, did not write the patch yourself, then
the very first line of the body should take the form From: <author name>
<author email>
, followed by a blank line. This will automatically cause the
named author to be credited with authorship in the repository.
Developer’s Certificate of Origin
To help track the author of a patch as well as the submission chain, and be clear that the developer has authority to submit a patch for inclusion in OVN please sign off your work. The sign off certifies the following:
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
See also http://developercertificate.org/.
Feature Deprecation Guidelines
OVN is intended to be user friendly. This means that under normal circumstances we don’t abruptly remove features from OVN 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 OVN is to:
Mention deprecation of a feature in the NEWS file. Also, mention expected release or absolute time when this feature would be removed from OVN altogether. Don’t use relative time (e.g. “in 6 months”) because that is not clearly interpretable.
If OVN 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.
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 follow-up and actually remove the feature from OVN codebase once deprecation grace period has expired and users had opportunity to use at least one OVN release that would have informed them about feature deprecation!
OVN upgrades
If the patch introduces any new OVN actions or updates existing OVN actions, then make sure to check the function ovn_get_internal_version() in lib/ovn-util.c and increment the macro - OVN_INTERNAL_MINOR_VER.
Adding new OVN actions or changing existing OVN actions can have datapath disruptions during OVN upgrades. To minimize disruptions, OVN supports version matching between ovn-northd and ovn-controller and it is important to update the internal OVN version when the patch introduces such changes.
Patch
The patch should be in the body of the email following the description, separated by a blank line.
Patches should be in diff -up
format. We recommend that you use Git to
produce your patches, in which case you should use the -M -C
options to
git diff
(or other Git tools) if your patch renames or copies files.
Quilt might be useful if you do
not want to use Git.
Patches should be inline in the email message. Some email clients corrupt white space or wrap lines in patches. There are hints on how to configure many email clients to avoid this problem on kernel.org. If you cannot convince your email client not to mangle patches, then sending the patch as an attachment is a second choice.
Follow the style used in the code that you are modifying. OVN Coding Style file describes the coding style used in most of OVN.
You may use the utilities/checkpatch.py
utility as a quick check
for certain commonly occurring mistakes (improper leading/trailing
whitespace, missing signoffs, some improper formatted patch files).
Example
From fa29a1c2c17682879e79a21bb0cdd5bbe67fa7c0 Mon Sep 17 00:00:00 2001
From: Jesse Gross <jesse@nicira.com>
Date: Thu, 8 Dec 2011 13:17:24 -0800
Subject: [PATCH] datapath: Alphabetize include/net/ipv6.h compat header.
Signed-off-by: Jesse Gross <jesse@nicira.com>
---
datapath/linux/Modules.mk | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/datapath/linux/Modules.mk b/datapath/linux/Modules.mk
index fdd952e..f6cb88e 100644
--- a/datapath/linux/Modules.mk
+++ b/datapath/linux/Modules.mk
@@ -56,11 +56,11 @@ openvswitch_headers += \
linux/compat/include/net/dst.h \
linux/compat/include/net/genetlink.h \
linux/compat/include/net/ip.h \
+ linux/compat/include/net/ipv6.h \
linux/compat/include/net/net_namespace.h \
linux/compat/include/net/netlink.h \
linux/compat/include/net/protocol.h \
linux/compat/include/net/route.h \
- linux/compat/include/net/ipv6.h \
linux/compat/genetlink.inc
both_modules += brcompat
--
1.7.7.3
Comments
If you want to include any comments in your email that should not be part of the commit’s change log message, put them after the description, separated by a line that contains just
---
. It may be helpful to include a diffstat here for changes that touch multiple files.