SubmittingPatches

   1 How to Submit Patches for Open vSwitch
   2 ======================================
   3
   4 Send changes to Open vSwitch as patches to discuss@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.18, 2.6.27, 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 Comments
 102 --------
 103
 104 If you want to include any comments in your email that should not be
 105 part of the commit's change log message, put them after the
 106 description, separated by a line that contains just "---".  It may be
 107 helpful to include a diffstat here for changes that touch multiple
 108 files.
 109
 110 Patch
 111 -----
 112
 113 The patch should be in the body of the email following the descrition,
 114 separated by a blank line.
 115
 116 Patches should be in "diff -up" format.  We recommend that you use Git
 117 to produce your patches, in which case you should use the -M -C
 118 options to "git diff" (or other Git tools) if your patch renames or
 119 copies files.  Quilt (http://savannah.nongnu.org/projects/quilt) might
 120 be useful if you do not want to use Git.
 121
 122 Patches should be inline in the email message.  Some email clients
 123 corrupt white space or wrap lines in patches.  There are hints on how
 124 to configure many email clients to avoid this problem at:
 125         http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/email-clients.txt
 126 If you cannot convince your email client not to mangle patches, then
 127 sending the patch as an attachment is a second choice.
 128
 129 Please follow the style used in the code that you are modifying.  The
 130 CodingStyle file describes the coding style used in most of Open
 131 vSwitch.  Use Linux kernel coding style for Linux kernel code.
 132
 133 Example
 134 -------
 135
 136 From 632d136c7b108cd3d39a2e64fe6230e23977caf8 Mon Sep 17 00:00:00 2001
 137 From: Ben Pfaff <blp@nicira.com>
 138 Date: Mon, 6 Jul 2009 10:17:54 -0700
 139 Subject: [PATCH] vswitch: Remove restriction on datapath names.
 140
 141 Commit f4b96c92c "vswitch: Disallow bridges named "dpN" or "nl:N"" disabled
 142 naming bridges "dpN" because the vswitchd code made the bad assumption that
 143 the bridge's local port has the same name as the bridge, which was not
 144 true (at the time) for bridges named dpN.  Now that assumption has been
 145 eliminated, so this commit eliminates the restriction too.
 146
 147 This change is also a cleanup in that it eliminates one form of the
 148 vswitch's dependence on specifics of the dpif implementation.
 149 ---
 150  vswitchd/bridge.c               |   23 +++++------------------
 151  vswitchd/ovs-vswitchd.conf.5.in |    3 +--
 152  2 files changed, 6 insertions(+), 20 deletions(-)
 153
 154 diff --git a/vswitchd/bridge.c b/vswitchd/bridge.c
 155 index 32647ea..00cffbc 100644
 156 --- a/vswitchd/bridge.c
 157 +++ b/vswitchd/bridge.c
 158 @@ -351,32 +351,19 @@ bridge_configure_ssl(void)
 159  void
 160  bridge_reconfigure(void)
 161  {
 162 -    struct svec old_br, new_br, raw_new_br;
 163 +    struct svec old_br, new_br;
 164      struct bridge *br, *next;
 165      size_t i, j;
 166
 167      COVERAGE_INC(bridge_reconfigure);
 168
 169 -    /* Collect old bridges. */
 170 +    /* Collect old and new bridges. */
 171      svec_init(&old_br);
 172 +    svec_init(&new_br);
 173      LIST_FOR_EACH (br, struct bridge, node, &all_bridges) {
 174          svec_add(&old_br, br->name);
 175      }
 176 -
 177 -    /* Collect new bridges. */
 178 -    svec_init(&raw_new_br);
 179 -    cfg_get_subsections(&raw_new_br, "bridge");
 180 -    svec_init(&new_br);
 181 -    for (i = 0; i < raw_new_br.n; i++) {
 182 -        const char *name = raw_new_br.names[i];
 183 -        if (!strncmp(name, "dp", 2) && isdigit((unsigned char)name[2])) {
 184 -            VLOG_ERR("%s is not a valid bridge name (bridges may not be "
 185 -                     "named \"dp\" followed by a digit)", name);
 186 -        } else {
 187 -            svec_add(&new_br, name);
 188 -        }
 189 -    }
 190 -    svec_destroy(&raw_new_br);
 191 +    cfg_get_subsections(&new_br, "bridge");
 192
 193      /* Get rid of deleted bridges and add new bridges. */
 194      svec_sort(&old_br);
 195 @@ -793,7 +780,7 @@ bridge_create(const char *name)
 196      br = xzalloc(sizeof *br);
 197
 198      error = dpif_create(name, &br->dpif);
 199 -    if (error == EEXIST) {
 200 +    if (error == EEXIST || error == EBUSY) {
 201          error = dpif_open(name, &br->dpif);
 202          if (error) {
 203              VLOG_ERR("datapath %s already exists but cannot be opened: %s",
 204 diff --git a/vswitchd/ovs-vswitchd.conf.5.in b/vswitchd/ovs-vswitchd.conf.5.in
 205 index 5483ad5..d82a08a 100644
 206 --- a/vswitchd/ovs-vswitchd.conf.5.in
 207 +++ b/vswitchd/ovs-vswitchd.conf.5.in
 208 @@ -50,8 +50,7 @@ configure \fBovs\-vswitchd\fR.
 209  .SS "Bridge Configuration"
 210  A bridge (switch) with a given \fIname\fR is configured by specifying
 211  the names of its network devices as values for key
 212 -\fBbridge.\fIname\fB.port\fR.  (The specified \fIname\fR may not begin
 213 -with \fBdp\fR followed by a digit.)
 214 +\fBbridge.\fIname\fB.port\fR.
 215  .PP
 216  The names given on \fBbridge.\fIname\fB.port\fR must be the names of
 217  existing network devices, except for ``internal ports.''  An internal
 218 --
 219 1.6.3.3
 220