CONTRIBUTING

   1 How to Submit Patches for Open vSwitch
   2 ======================================
   3
   4 Send changes to Open vSwitch as patches to dev@openvswitch.org.
   5 One patch per email, please.  More details are included below.
   6
   7 If you are using Git, then "git format-patch" takes care of most of
   8 the mechanics described below for you.
   9
  10 Before You Start
  11 ----------------
  12
  13 Before you send patches at all, make sure that each patch makes sense.
  14 In particular:
  15
  16         - A given patch should not break anything, even if later
  17           patches fix the problems that it causes.  The source tree
  18           should still build and work after each patch is applied.
  19           (This enables "git bisect" to work best.)
  20
  21         - A patch should make one logical change.  Don't make
  22           multiple, logically unconnected changes to disparate
  23           subsystems in a single patch.
  24
  25         - A patch that adds or removes user-visible features should
  26           also update the appropriate user documentation or manpages.
  27
  28 Testing is also important:
  29
  30         - A patch that adds or deletes files should be tested with
  31           "make distcheck" before submission.
  32
  33         - A patch that modifies Linux kernel code should be at least
  34           build-tested on various Linux kernel versions before
  35           submission.  I suggest versions 2.6.32 and whatever
  36           the current latest release version is at the time.
  37
  38         - A patch that modifies the ofproto or vswitchd code should be
  39           tested in at least simple cases before submission.
  40
  41         - A patch that modifies xenserver code should be tested on
  42           XenServer before submission.
  43
  44 Email Subject
  45 -------------
  46
  47 The subject line of your email should be in the following format:
  48 [PATCH <n>/<m>] <area>: <summary>
  49
  50         - [PATCH <n>/<m>] indicates that this is the nth of a series
  51           of m patches.  It helps reviewers to read patches in the
  52           correct order.  You may omit this prefix if you are sending
  53           only one patch.
  54
  55         - <area>: indicates the area of the Open vSwitch to which the
  56           change applies (often the name of a source file or a
  57           directory).  You may omit it if the change crosses multiple
  58           distinct pieces of code.
  59
  60         - <summary> briefly describes the change.
  61
  62 The subject, minus the [PATCH <n>/<m>] prefix, becomes the first line
  63 of the commit's change log message.
  64
  65 Description
  66 -----------
  67
  68 The body of the email should start with a more thorough description of
  69 the change.  This becomes the body of the commit message, following
  70 the subject.  There is no need to duplicate the summary given in the
  71 subject.
  72
  73 Please limit lines in the description to 79 characters in width.
  74
  75 The description should include:
  76
  77         - The rationale for the change.
  78
  79         - Design description and rationale (but this might be better
  80           added as code comments).
  81
  82         - Testing that you performed (or testing that should be done
  83           but you could not for whatever reason).
  84
  85 There is no need to describe what the patch actually changed, if the
  86 reader can see it for himself.
  87
  88 If the patch refers to a commit already in the Open vSwitch
  89 repository, please include both the commit number and the subject of
  90 the patch, e.g. 'commit 632d136c (vswitch: Remove restriction on
  91 datapath names.)'.
  92
  93 If you, the person sending the patch, did not write the patch
  94 yourself, then the very first line of the body should take the form
  95 "From: <author name> <author email>", followed by a blank line.  This
  96 will automatically cause the named author to be credited with
  97 authorship in the repository.  If others contributed to the patch, but
  98 are not the main authors, then please credit them as part of the
  99 description (e.g. "Thanks to Bob J. User for reporting this bug.").
 100
 101 Please sign off on the patch as a submitter, and be sure to have the
 102 author(s) sign off for patches that you did not author.
 103
 104 Simply include your name and email address as the last line of the commit
 105 message before any comments (and author too, if that is not you):
 106
 107 Signed-off-by: Author Name <author.name@email.address...>
 108 Signed-off-by: Submitter Name <submitter.name@email.address...>
 109
 110 By doing this, you are agreeing to the Developer's Certificate of Origin
 111 (see below for more details).
 112
 113 Developer's Certificate of Origin
 114 ---------------------------------
 115
 116 To help track the author of a patch as well as the submission chain,
 117 and be clear that the developer has authority to submit a patch for
 118 inclusion in openvswitch please sign off your work.  The sign off
 119 certifies the following:
 120
 121     Developer's Certificate of Origin 1.1
 122
 123     By making a contribution to this project, I certify that:
 124
 125     (a) The contribution was created in whole or in part by me and I
 126         have the right to submit it under the open source license
 127         indicated in the file; or
 128
 129     (b) The contribution is based upon previous work that, to the best
 130         of my knowledge, is covered under an appropriate open source
 131         license and I have the right under that license to submit that
 132         work with modifications, whether created in whole or in part
 133         by me, under the same open source license (unless I am
 134         permitted to submit under a different license), as indicated
 135         in the file; or
 136
 137     (c) The contribution was provided directly to me by some other
 138         person who certified (a), (b) or (c) and I have not modified
 139         it.
 140
 141     (d) I understand and agree that this project and the contribution
 142         are public and that a record of the contribution (including all
 143         personal information I submit with it, including my sign-off) is
 144         maintained indefinitely and may be redistributed consistent with
 145         this project or the open source license(s) involved.
 146
 147 Comments
 148 --------
 149
 150 If you want to include any comments in your email that should not be
 151 part of the commit's change log message, put them after the
 152 description, separated by a line that contains just "---".  It may be
 153 helpful to include a diffstat here for changes that touch multiple
 154 files.
 155
 156 Patch
 157 -----
 158
 159 The patch should be in the body of the email following the description,
 160 separated by a blank line.
 161
 162 Patches should be in "diff -up" format.  We recommend that you use Git
 163 to produce your patches, in which case you should use the -M -C
 164 options to "git diff" (or other Git tools) if your patch renames or
 165 copies files.  Quilt (http://savannah.nongnu.org/projects/quilt) might
 166 be useful if you do not want to use Git.
 167
 168 Patches should be inline in the email message.  Some email clients
 169 corrupt white space or wrap lines in patches.  There are hints on how
 170 to configure many email clients to avoid this problem at:
 171         http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/email-clients.txt
 172 If you cannot convince your email client not to mangle patches, then
 173 sending the patch as an attachment is a second choice.
 174
 175 Please follow the style used in the code that you are modifying.  The
 176 CodingStyle file describes the coding style used in most of Open
 177 vSwitch.  Use Linux kernel coding style for Linux kernel code.
 178
 179 Example
 180 -------
 181
 182 From fa29a1c2c17682879e79a21bb0cdd5bbe67fa7c0 Mon Sep 17 00:00:00 2001
 183 From: Jesse Gross <jesse@nicira.com>
 184 Date: Thu, 8 Dec 2011 13:17:24 -0800
 185 Subject: [PATCH] datapath: Alphabetize include/net/ipv6.h compat header.
 186
 187 Signed-off-by: Jesse Gross <jesse@nicira.com>
 188 ---
 189  datapath/linux/Modules.mk |    2 +-
 190  1 files changed, 1 insertions(+), 1 deletions(-)
 191
 192 diff --git a/datapath/linux/Modules.mk b/datapath/linux/Modules.mk
 193 index fdd952e..f6cb88e 100644
 194 --- a/datapath/linux/Modules.mk
 195 +++ b/datapath/linux/Modules.mk
 196 @@ -56,11 +56,11 @@ openvswitch_headers += \
 197         linux/compat/include/net/dst.h \
 198         linux/compat/include/net/genetlink.h \
 199         linux/compat/include/net/ip.h \
 200 +       linux/compat/include/net/ipv6.h \
 201         linux/compat/include/net/net_namespace.h \
 202         linux/compat/include/net/netlink.h \
 203         linux/compat/include/net/protocol.h \
 204         linux/compat/include/net/route.h \
 205 -       linux/compat/include/net/ipv6.h \
 206         linux/compat/genetlink.inc
 207
 208  both_modules += brcompat
 209 --
 210 1.7.7.3
 211