Skip to content

Latest commit

 

History

History
230 lines (160 loc) · 8.51 KB

CONTRIBUTING.md

File metadata and controls

230 lines (160 loc) · 8.51 KB
Raw

Contributing to Intel(R) DPDK vSwitch

Mailing List

The official [mailing list][mail_list] is the prefered channel for all questions, bug reports and patch submissions.

Submitting Patches

Good patches are a huge help, and the best way to get your bug fixes, new features, and performance improvements into the project. All changes should be sent as patches to [email protected], in the form of one patch per email. Here are a few guidelines for submitting patches:

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.

  • A patch adding new functionality should be made against the HEAD of the development branch.

Testing is also important:

  • A patch is expected to not break currently functioning ovs-testsuite or OFTest tests.

  • If you add any significantly new functionality, a test should be provided.

  • A patch that modifies Linux kernel code should be at least build-tested on various Linux kernel versions before submission. We suggest versions 2.6.18, 2.6.27, and whatever the current latest release version is at the time.

Email Subject

There should only be one patch per email. The subject line of your email should be in the following format:

[PATCH <n>/<m>] <area>: <summary>

  • [PATCH <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 the Intel (R) DPDK vSwitch 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.

The subject, minus the [PATCH <n>/<m>] prefix, becomes the first line of the commit's change log message.

To prepare a patch, it must be saved with git commit. All patches must be generated with git send-email. This will take care of most of the mechanics described below for you.

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 79 characters in width.

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).

There is no need to describe what the patch actually changed, if the reader can see it for themselves.

If the patch refers to a commit already in the Intel DPDK vSwitch 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, followed by a blank line:

From: <author name> <author email>

This will automatically cause the named author to be credited with authorship in the repository. If others contributed to the patch, but are not the main authors, then please credit them as part of the description, e.g.

Thanks to Bob J. User for reporting this bug.

Please sign off on the patch as a submitter, and be sure to have the author(s) sign off for patches that you did not author. Simply include your name and email address as the last line of the commit message before any comments (and author too, if that is not you):

Signed-off-by: Author Name <[email protected]...>
Signed-off-by: Submitter Name <[email protected]...>

By doing this, you are agreeing to the Developer's Certificate of Origin (see below for more details).

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 openvswitch 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.

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.

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 here. 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.

Example

From fa29a1c2c17682879e79a21bb0cdd5bbe67fa7c0 Mon Sep 17 00:00:00 2001
From: Jesse Gross <[email protected]>
Date: Thu, 8 Dec 2011 13:17:24 -0800
Subject: [PATCH] datapath: Alphabetize include/net/ipv6.h compat header.

Signed-off-by: Jesse Gross <[email protected]>
---
 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

After You Finish

Please test your patch to ensure that it applied cleanly. You can do this by saving the e-mail (as, for example, email.txt) and applying it to the GitHub repository.

  • Pull the latest changes

    git pull origin

  • Make sure you are on 'development'

    git checkout development

  • Apply the email

    git am email.txt

If everything is done correctly, the email should apply correctly.