1 How to Submit Patches for Open vSwitch
2 ======================================
4 Send changes to Open vSwitch as patches to dev@openvswitch.org.
5 One patch per email, please. More details are included below.
7 If you are using Git, then `git format-patch` takes care of most of
8 the mechanics described below for you.
13 Before you send patches at all, make sure that each patch makes sense.
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.)
21 - A patch should make one logical change. Don't make
22 multiple, logically unconnected changes to disparate
23 subsystems in a single patch.
25 - A patch that adds or removes user-visible features should
26 also update the appropriate user documentation or manpages.
27 Check "Feature Deprecation Guidelines" section in this document
28 if you intend to remove user-visible feature.
30 Testing is also important:
32 - A patch that modifies existing code should be tested with
33 `make check` before submission.
35 - A patch that adds or deletes files should also be tested with
36 `make distcheck` before submission.
38 - A patch that modifies Linux kernel code should be at least
39 build-tested on various Linux kernel versions before
40 submission. I suggest versions 2.6.32 and whatever
41 the current latest release version is at the time.
43 - A patch that modifies the ofproto or vswitchd code should be
44 tested in at least simple cases before submission.
46 - A patch that modifies xenserver code should be tested on
47 XenServer before submission.
49 If you are using GitHub, then you may utilize the travis-ci.org CI build
50 system by linking your GitHub repository to it. This will run some of
51 the above tests automatically when you push changes to your repository.
52 See the "Continuous Integration with Travis-CI" in the [INSTALL.md] file
53 for details on how to set it up.
58 The subject line of your email should be in the following format:
59 `[PATCH <n>/<m>] <area>: <summary>`
61 - `[PATCH <n>/<m>]` indicates that this is the nth of a series
62 of m patches. It helps reviewers to read patches in the
63 correct order. You may omit this prefix if you are sending
66 - `<area>:` indicates the area of the Open vSwitch to which the
67 change applies (often the name of a source file or a
68 directory). You may omit it if the change crosses multiple
69 distinct pieces of code.
71 - `<summary>` briefly describes the change.
73 The subject, minus the `[PATCH <n>/<m>]` prefix, becomes the first line
74 of the commit's change log message.
79 The body of the email should start with a more thorough description of
80 the change. This becomes the body of the commit message, following
81 the subject. There is no need to duplicate the summary given in the
84 Please limit lines in the description to 79 characters in width.
86 The description should include:
88 - The rationale for the change.
90 - Design description and rationale (but this might be better
91 added as code comments).
93 - Testing that you performed (or testing that should be done
94 but you could not for whatever reason).
98 There is no need to describe what the patch actually changed, if the
99 reader can see it for himself.
101 If the patch refers to a commit already in the Open vSwitch
102 repository, please include both the commit number and the subject of
103 the patch, e.g. 'commit 632d136c (vswitch: Remove restriction on
106 If you, the person sending the patch, did not write the patch
107 yourself, then the very first line of the body should take the form
108 `From: <author name> <author email>`, followed by a blank line. This
109 will automatically cause the named author to be credited with
110 authorship in the repository.
115 The description ends with a series of tags, written one to a line as
116 the last paragraph of the email. Each tag indicates some property of
117 the patch in an easily machine-parseable manner.
119 Examples of common tags follow.
121 Signed-off-by: Author Name <author.name@email.address...>
123 Informally, this indicates that Author Name is the author or
124 submitter of a patch and has the authority to submit it under
125 the terms of the license. The formal meaning is to agree to
126 the Developer's Certificate of Origin (see below).
128 If the author and submitter are different, each must sign off.
129 If the patch has more than one author, all must sign off.
131 Signed-off-by: Author Name <author.name@email.address...>
132 Signed-off-by: Submitter Name <submitter.name@email.address...>
134 Co-authored-by: Author Name <author.name@email.address...>
136 Git can only record a single person as the author of a given
137 patch. In the rare event that a patch has multiple authors,
138 one must be given the credit in Git and the others must be
139 credited via Co-authored-by: tags. (All co-authors must also
142 Acked-by: Reviewer Name <reviewer.name@email.address...>
144 Reviewers will often give an Acked-by: tag to code of which
145 they approve. It is polite for the submitter to add the tag
146 before posting the next version of the patch or applying the
147 patch to the repository. Quality reviewing is hard work, so
148 this gives a small amount of credit to the reviewer.
150 Not all reviewers give Acked-by: tags when they provide
151 positive reviews. It's customary only to add tags from
152 reviewers who actually provide them explicitly.
154 Tested-by: Tester Name <reviewer.name@email.address...>
156 When someone tests a patch, it is customary to add a
157 Tested-by: tag indicating that. It's rare for a tester to
158 actually provide the tag; usually the patch submitter makes
159 the tag himself in response to an email indicating successful
164 When a test report is publicly available, this provides a way
165 to reference it. Typical <URL>s would be build logs from
166 autobuilders or references to mailing list archives.
168 Some autobuilders only retain their logs for a limited amount
169 of time. It is less useful to cite these because they may be
170 dead links for a developer reading the commit message months
173 Reported-by: Reporter Name <reporter.name@email.address...>
175 When a patch fixes a bug reported by some person, please
176 credit the reporter in the commit log in this fashion. Please
177 also add the reporter's name and email address to the list of
178 people who provided helpful bug reports in the AUTHORS file at
179 the top of the source tree.
181 Fairly often, the reporter of a bug also tests the fix.
182 Occasionally one sees a combined "Reported-and-tested-by:" tag
183 used to indicate this. It is also acceptable, and more
184 common, to include both tags separately.
186 (If a bug report is received privately, it might not always be
187 appropriate to publicly credit the reporter. If in doubt,
188 please ask the reporter.)
190 Requested-by: Requester Name <requester.name@email.address...>
191 Suggested-by: Suggester Name <suggester.name@email.address...>
193 When a patch implements a request or a suggestion made by some
194 person, please credit that person in the commit log in this
195 fashion. For a helpful suggestion, please also add the
196 person's name and email address to the list of people who
197 provided suggestions in the AUTHORS file at the top of the
200 (If a suggestion or a request is received privately, it might
201 not always be appropriate to publicly give credit. If in
206 If a patch fixes or is otherwise related to a bug reported in
207 a public bug tracker, please include a reference to the bug in
208 the form of a URL to the specific bug, e.g.:
210 Reported-at: https://bugs.debian.org/743635
212 This is also an appropriate way to refer to bug report emails
213 in public email archives, e.g.:
215 Reported-at: http://openvswitch.org/pipermail/dev/2014-June/040952.html
220 If a patch fixes or is otherwise related to a bug reported in
221 a private bug tracker, you may include some tracking ID for
222 the bug for your own reference. Please include some
223 identifier to make the origin clear, e.g. "VMware-BZ" refers
224 to VMware's internal Bugzilla instance and "ONF-JIRA" refers
225 to the Open Networking Foundation's JIRA bug tracker.
230 These are obsolete forms of VMware-BZ: that can still be seen
231 in old change log entries. (They are obsolete because they do
232 not tell the reader what bug tracker is referred to.)
234 Developer's Certificate of Origin
235 ---------------------------------
237 To help track the author of a patch as well as the submission chain,
238 and be clear that the developer has authority to submit a patch for
239 inclusion in openvswitch please sign off your work. The sign off
240 certifies the following:
242 Developer's Certificate of Origin 1.1
244 By making a contribution to this project, I certify that:
246 (a) The contribution was created in whole or in part by me and I
247 have the right to submit it under the open source license
248 indicated in the file; or
250 (b) The contribution is based upon previous work that, to the best
251 of my knowledge, is covered under an appropriate open source
252 license and I have the right under that license to submit that
253 work with modifications, whether created in whole or in part
254 by me, under the same open source license (unless I am
255 permitted to submit under a different license), as indicated
258 (c) The contribution was provided directly to me by some other
259 person who certified (a), (b) or (c) and I have not modified
262 (d) I understand and agree that this project and the contribution
263 are public and that a record of the contribution (including all
264 personal information I submit with it, including my sign-off) is
265 maintained indefinitely and may be redistributed consistent with
266 this project or the open source license(s) involved.
268 Feature Deprecation Guidelines
269 ------------------------------
271 Open vSwitch is intended to be user friendly. This means that under
272 normal circumstances we don't abruptly remove features from OVS that
273 some users might still be using. Otherwise, if we would, then we would
274 possibly break our user setup when they upgrade and would receive bug
277 Typical process to deprecate a feature in Open vSwitch is to:
279 (a) Mention deprecation of a feature in the NEWS file. Also, mention
280 expected release or absolute time when this feature would be removed
281 from OVS altogether. Don't use relative time (e.g. "in 6 months")
282 because that is not clearly interpretable.
284 (b) If Open vSwitch is configured to use deprecated feature it should print
285 a warning message to the log files clearly indicating that feature is
286 deprecated and that use of it should be avoided.
288 (c) If this feature is mentioned in man pages, then add "Deprecated" keyword
291 Also, if there is alternative feature to the one that is about to be marked
292 as deprecated, then mention it in (a), (b) and (c) as well.
294 Remember to followup and actually remove the feature from OVS codebase
295 once deprecation grace period has expired and users had opportunity to
296 use at least one OVS release that would have informed them about feature
302 If you want to include any comments in your email that should not be
303 part of the commit's change log message, put them after the
304 description, separated by a line that contains just `---`. It may be
305 helpful to include a diffstat here for changes that touch multiple
311 The patch should be in the body of the email following the description,
312 separated by a blank line.
314 Patches should be in `diff -up` format. We recommend that you use Git
315 to produce your patches, in which case you should use the `-M -C`
316 options to `git diff` (or other Git tools) if your patch renames or
317 copies files. Quilt (http://savannah.nongnu.org/projects/quilt) might
318 be useful if you do not want to use Git.
320 Patches should be inline in the email message. Some email clients
321 corrupt white space or wrap lines in patches. There are hints on how
322 to configure many email clients to avoid this problem at:
323 http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/email-clients.txt
324 If you cannot convince your email client not to mangle patches, then
325 sending the patch as an attachment is a second choice.
327 Please follow the style used in the code that you are modifying. The
328 [CodingStyle.md] file describes the coding style used in most of Open
329 vSwitch. Use Linux kernel coding style for Linux kernel code.
335 From fa29a1c2c17682879e79a21bb0cdd5bbe67fa7c0 Mon Sep 17 00:00:00 2001
336 From: Jesse Gross <jesse@nicira.com>
337 Date: Thu, 8 Dec 2011 13:17:24 -0800
338 Subject: [PATCH] datapath: Alphabetize include/net/ipv6.h compat header.
340 Signed-off-by: Jesse Gross <jesse@nicira.com>
342 datapath/linux/Modules.mk | 2 +-
343 1 files changed, 1 insertions(+), 1 deletions(-)
345 diff --git a/datapath/linux/Modules.mk b/datapath/linux/Modules.mk
346 index fdd952e..f6cb88e 100644
347 --- a/datapath/linux/Modules.mk
348 +++ b/datapath/linux/Modules.mk
349 @@ -56,11 +56,11 @@ openvswitch_headers += \
350 linux/compat/include/net/dst.h \
351 linux/compat/include/net/genetlink.h \
352 linux/compat/include/net/ip.h \
353 + linux/compat/include/net/ipv6.h \
354 linux/compat/include/net/net_namespace.h \
355 linux/compat/include/net/netlink.h \
356 linux/compat/include/net/protocol.h \
357 linux/compat/include/net/route.h \
358 - linux/compat/include/net/ipv6.h \
359 linux/compat/genetlink.inc
361 both_modules += brcompat
366 [INSTALL.md]:INSTALL.md
367 [CodingStyle.md]:CodingStyle.md