CONTRIBUTING.md

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