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         - Tags (see below).
  86
  87 There is no need to describe what the patch actually changed, if the
  88 reader can see it for himself.
  89
  90 If the patch refers to a commit already in the Open vSwitch
  91 repository, please include both the commit number and the subject of
  92 the patch, e.g. 'commit 632d136c (vswitch: Remove restriction on
  93 datapath names.)'.
  94
  95 If you, the person sending the patch, did not write the patch
  96 yourself, then the very first line of the body should take the form
  97 "From: <author name> <author email>", followed by a blank line.  This
  98 will automatically cause the named author to be credited with
  99 authorship in the repository.
 100
 101 Tags
 102 ----
 103
 104 The description ends with a series of tags, written one to a line as
 105 the last paragraph of the email.  Each tag indicates some property of
 106 the patch in an easily machine-parseable manner.
 107
 108 Examples of common tags follow.
 109
 110     Signed-off-by: Author Name <author.name@email.address...>
 111
 112         Informally, this indicates that Author Name is the author or
 113         submitter of a patch and has the authority to submit it under
 114         the terms of the license.  The formal meaning is to agree to
 115         the Developer's Certificate of Origin (see below).
 116
 117         If the author and submitter are different, each must sign off.
 118         If the patch has more than one author, all must sign off.
 119
 120         Signed-off-by: Author Name <author.name@email.address...>
 121         Signed-off-by: Submitter Name <submitter.name@email.address...>
 122
 123     Co-authored-by: Author Name <author.name@email.address...>
 124
 125         Git can only record a single person as the author of a given
 126         patch.  In the rare event that a patch has multiple authors,
 127         one must be given the credit in Git and the others must be
 128         credited via Co-authored-by: tags.  (All co-authors must also
 129         sign off.)
 130
 131     Acked-by: Reviewer Name <reviewer.name@email.address...>
 132
 133         Reviewers will often give an Acked-by: tag to code of which
 134         they approve.  It is polite for the submitter to add the tag
 135         before posting the next version of the patch or applying the
 136         patch to the repository.  Quality reviewing is hard work, so
 137         this gives a small amount of credit to the reviewer.
 138
 139         Not all reviewers give Acked-by: tags when they provide
 140         positive reviews.  It's customary only to add tags from
 141         reviewers who actually provide them explicitly.
 142
 143     Tested-by: Tester Name <reviewer.name@email.address...>
 144
 145         When someone tests a patch, it is customary to add a
 146         Tested-by: tag indicating that.  It's rare for a tester to
 147         actually provide the tag; usually the patch submitter makes
 148         the tag himself in response to an email indicating successful
 149         testing results.
 150
 151     Reported-by: Reporter Name <reporter.name@email.address...>
 152
 153         When a patch fixes a bug reported by some person, please
 154         credit the reporter in the commit log in this fashion.  Please
 155         also add the reporter's name and email address to the list of
 156         people who provided helpful bug reports in the AUTHORS file at
 157         the top of the source tree.
 158
 159         Fairly often, the reporter of a bug also tests the fix.
 160         Occasionally one sees a combined "Reported-and-tested-by:" tag
 161         used to indicate this.  It is also acceptable, and more
 162         common, to include both tags separately.
 163
 164         (If a bug report is received privately, it might not always be
 165         appropriate to publicly credit the reporter.  If in doubt,
 166         please ask the reporter.)
 167
 168     Requested-by: Requester Name <requester.name@email.address...>
 169     Suggested-by: Suggester Name <suggester.name@email.address...>
 170
 171         When a patch implements a request or a suggestion made by some
 172         person, please credit that person in the commit log in this
 173         fashion.  For a helpful suggestion, please also add the
 174         person's name and email address to the list of people who
 175         provided suggestions in the AUTHORS file at the top of the
 176         source tree.
 177
 178         (If a suggestion or a request is received privately, it might
 179         not always be appropriate to publicly give credit.  If in
 180         doubt, please ask.)
 181
 182     Reported-at: <URL>
 183
 184         If a patch fixes or is otherwise related to a bug reported in
 185         a public bug tracker, please include a reference to the bug in
 186         the form of a URL to the specific bug, e.g.:
 187
 188         Reported-at: https://bugs.debian.org/743635
 189
 190         This is also an appropriate way to refer to bug report emails
 191         in public email archives, e.g.:
 192
 193         Reported-at: http://openvswitch.org/pipermail/dev/2014-June/040952.html
 194
 195     VMware-BZ: #1234567
 196     ONF-JIRA: EXT-12345
 197
 198         If a patch fixes or is otherwise related to a bug reported in
 199         a private bug tracker, you may include some tracking ID for
 200         the bug for your own reference.  Please include some
 201         identifier to make the origin clear, e.g. "VMware-BZ" refers
 202         to VMware's internal Bugzilla instance and "ONF-JIRA" refers
 203         to the Open Networking Foundation's JIRA bug tracker.
 204
 205     Bug #1234567.
 206     Issue: 1234567
 207
 208         These are obsolete forms of VMware-BZ: that can still be seen
 209         in old change log entries.  (They are obsolete because they do
 210         not tell the reader what bug tracker is referred to.)
 211
 212 Developer's Certificate of Origin
 213 ---------------------------------
 214
 215 To help track the author of a patch as well as the submission chain,
 216 and be clear that the developer has authority to submit a patch for
 217 inclusion in openvswitch please sign off your work.  The sign off
 218 certifies the following:
 219
 220     Developer's Certificate of Origin 1.1
 221
 222     By making a contribution to this project, I certify that:
 223
 224     (a) The contribution was created in whole or in part by me and I
 225         have the right to submit it under the open source license
 226         indicated in the file; or
 227
 228     (b) The contribution is based upon previous work that, to the best
 229         of my knowledge, is covered under an appropriate open source
 230         license and I have the right under that license to submit that
 231         work with modifications, whether created in whole or in part
 232         by me, under the same open source license (unless I am
 233         permitted to submit under a different license), as indicated
 234         in the file; or
 235
 236     (c) The contribution was provided directly to me by some other
 237         person who certified (a), (b) or (c) and I have not modified
 238         it.
 239
 240     (d) I understand and agree that this project and the contribution
 241         are public and that a record of the contribution (including all
 242         personal information I submit with it, including my sign-off) is
 243         maintained indefinitely and may be redistributed consistent with
 244         this project or the open source license(s) involved.
 245
 246 Comments
 247 --------
 248
 249 If you want to include any comments in your email that should not be
 250 part of the commit's change log message, put them after the
 251 description, separated by a line that contains just "---".  It may be
 252 helpful to include a diffstat here for changes that touch multiple
 253 files.
 254
 255 Patch
 256 -----
 257
 258 The patch should be in the body of the email following the description,
 259 separated by a blank line.
 260
 261 Patches should be in "diff -up" format.  We recommend that you use Git
 262 to produce your patches, in which case you should use the -M -C
 263 options to "git diff" (or other Git tools) if your patch renames or
 264 copies files.  Quilt (http://savannah.nongnu.org/projects/quilt) might
 265 be useful if you do not want to use Git.
 266
 267 Patches should be inline in the email message.  Some email clients
 268 corrupt white space or wrap lines in patches.  There are hints on how
 269 to configure many email clients to avoid this problem at:
 270         http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/email-clients.txt
 271 If you cannot convince your email client not to mangle patches, then
 272 sending the patch as an attachment is a second choice.
 273
 274 Please follow the style used in the code that you are modifying.  The
 275 CodingStyle file describes the coding style used in most of Open
 276 vSwitch.  Use Linux kernel coding style for Linux kernel code.
 277
 278 Example
 279 -------
 280
 281 From fa29a1c2c17682879e79a21bb0cdd5bbe67fa7c0 Mon Sep 17 00:00:00 2001
 282 From: Jesse Gross <jesse@nicira.com>
 283 Date: Thu, 8 Dec 2011 13:17:24 -0800
 284 Subject: [PATCH] datapath: Alphabetize include/net/ipv6.h compat header.
 285
 286 Signed-off-by: Jesse Gross <jesse@nicira.com>
 287 ---
 288  datapath/linux/Modules.mk |    2 +-
 289  1 files changed, 1 insertions(+), 1 deletions(-)
 290
 291 diff --git a/datapath/linux/Modules.mk b/datapath/linux/Modules.mk
 292 index fdd952e..f6cb88e 100644
 293 --- a/datapath/linux/Modules.mk
 294 +++ b/datapath/linux/Modules.mk
 295 @@ -56,11 +56,11 @@ openvswitch_headers += \
 296         linux/compat/include/net/dst.h \
 297         linux/compat/include/net/genetlink.h \
 298         linux/compat/include/net/ip.h \
 299 +       linux/compat/include/net/ipv6.h \
 300         linux/compat/include/net/net_namespace.h \
 301         linux/compat/include/net/netlink.h \
 302         linux/compat/include/net/protocol.h \
 303         linux/compat/include/net/route.h \
 304 -       linux/compat/include/net/ipv6.h \
 305         linux/compat/genetlink.inc
 306
 307  both_modules += brcompat
 308 --
 309 1.7.7.3
 310