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