1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 .. _netdev-FAQ: 3 .. _netdev-FAQ:
4 4
5 ============================= 5 =============================
6 Networking subsystem (netdev) 6 Networking subsystem (netdev)
7 ============================= 7 =============================
8 8
9 tl;dr 9 tl;dr
10 ----- 10 -----
11 11
12 - designate your patch to a tree - ``[PATCH n 12 - designate your patch to a tree - ``[PATCH net]`` or ``[PATCH net-next]``
13 - for fixes the ``Fixes:`` tag is required, r 13 - for fixes the ``Fixes:`` tag is required, regardless of the tree
14 - don't post large series (> 15 patches), bre 14 - don't post large series (> 15 patches), break them up
15 - don't repost your patches within one 24h pe 15 - don't repost your patches within one 24h period
16 - reverse xmas tree 16 - reverse xmas tree
17 17
18 netdev 18 netdev
19 ------ 19 ------
20 20
21 netdev is a mailing list for all network-relat 21 netdev is a mailing list for all network-related Linux stuff. This
22 includes anything found under net/ (i.e. core 22 includes anything found under net/ (i.e. core code like IPv6) and
23 drivers/net (i.e. hardware specific drivers) i 23 drivers/net (i.e. hardware specific drivers) in the Linux source tree.
24 24
25 Note that some subsystems (e.g. wireless drive 25 Note that some subsystems (e.g. wireless drivers) which have a high
26 volume of traffic have their own specific mail 26 volume of traffic have their own specific mailing lists and trees.
27 27
28 Like many other Linux mailing lists, the netde !! 28 The netdev list is managed (like many other Linux mailing lists) through
29 kernel.org with archives available at https:// !! 29 VGER (http://vger.kernel.org/) with archives available at
>> 30 https://lore.kernel.org/netdev/
30 31
31 Aside from subsystems like those mentioned abo 32 Aside from subsystems like those mentioned above, all network-related
32 Linux development (i.e. RFC, review, comments, 33 Linux development (i.e. RFC, review, comments, etc.) takes place on
33 netdev. 34 netdev.
34 35
35 Development cycle 36 Development cycle
36 ----------------- 37 -----------------
37 38
38 Here is a bit of background information on 39 Here is a bit of background information on
39 the cadence of Linux development. Each new re 40 the cadence of Linux development. Each new release starts off with a
40 two week "merge window" where the main maintai 41 two week "merge window" where the main maintainers feed their new stuff
41 to Linus for merging into the mainline tree. 42 to Linus for merging into the mainline tree. After the two weeks, the
42 merge window is closed, and it is called/tagge 43 merge window is closed, and it is called/tagged ``-rc1``. No new
43 features get mainlined after this -- only fixe 44 features get mainlined after this -- only fixes to the rc1 content are
44 expected. After roughly a week of collecting 45 expected. After roughly a week of collecting fixes to the rc1 content,
45 rc2 is released. This repeats on a roughly we 46 rc2 is released. This repeats on a roughly weekly basis until rc7
46 (typically; sometimes rc6 if things are quiet, 47 (typically; sometimes rc6 if things are quiet, or rc8 if things are in a
47 state of churn), and a week after the last vX. 48 state of churn), and a week after the last vX.Y-rcN was done, the
48 official vX.Y is released. 49 official vX.Y is released.
49 50
50 To find out where we are now in the cycle - lo 51 To find out where we are now in the cycle - load the mainline (Linus)
51 page here: 52 page here:
52 53
53 https://git.kernel.org/pub/scm/linux/kernel/ 54 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
54 55
55 and note the top of the "tags" section. If it 56 and note the top of the "tags" section. If it is rc1, it is early in
56 the dev cycle. If it was tagged rc7 a week ag 57 the dev cycle. If it was tagged rc7 a week ago, then a release is
57 probably imminent. If the most recent tag is a 58 probably imminent. If the most recent tag is a final release tag
58 (without an ``-rcN`` suffix) - we are most lik 59 (without an ``-rcN`` suffix) - we are most likely in a merge window
59 and ``net-next`` is closed. 60 and ``net-next`` is closed.
60 61
61 git trees and patch flow 62 git trees and patch flow
62 ------------------------ 63 ------------------------
63 64
64 There are two networking trees (git repositori 65 There are two networking trees (git repositories) in play. Both are
65 driven by David Miller, the main network maint 66 driven by David Miller, the main network maintainer. There is the
66 ``net`` tree, and the ``net-next`` tree. As y 67 ``net`` tree, and the ``net-next`` tree. As you can probably guess from
67 the names, the ``net`` tree is for fixes to ex 68 the names, the ``net`` tree is for fixes to existing code already in the
68 mainline tree from Linus, and ``net-next`` is 69 mainline tree from Linus, and ``net-next`` is where the new code goes
69 for the future release. You can find the tree 70 for the future release. You can find the trees here:
70 71
71 - https://git.kernel.org/pub/scm/linux/kernel/ 72 - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git
72 - https://git.kernel.org/pub/scm/linux/kernel/ 73 - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git
73 74
74 Relating that to kernel development: At the be 75 Relating that to kernel development: At the beginning of the 2-week
75 merge window, the ``net-next`` tree will be cl 76 merge window, the ``net-next`` tree will be closed - no new changes/features.
76 The accumulated new content of the past ~10 we 77 The accumulated new content of the past ~10 weeks will be passed onto
77 mainline/Linus via a pull request for vX.Y -- 78 mainline/Linus via a pull request for vX.Y -- at the same time, the
78 ``net`` tree will start accumulating fixes for 79 ``net`` tree will start accumulating fixes for this pulled content
79 relating to vX.Y 80 relating to vX.Y
80 81
81 An announcement indicating when ``net-next`` h 82 An announcement indicating when ``net-next`` has been closed is usually
82 sent to netdev, but knowing the above, you can 83 sent to netdev, but knowing the above, you can predict that in advance.
83 84
84 .. warning:: 85 .. warning::
85 Do not send new ``net-next`` content to netd 86 Do not send new ``net-next`` content to netdev during the
86 period during which ``net-next`` tree is clo 87 period during which ``net-next`` tree is closed.
87 88
88 RFC patches sent for review only are obviously 89 RFC patches sent for review only are obviously welcome at any time
89 (use ``--subject-prefix='RFC net-next'`` with 90 (use ``--subject-prefix='RFC net-next'`` with ``git format-patch``).
90 91
91 Shortly after the two weeks have passed (and v 92 Shortly after the two weeks have passed (and vX.Y-rc1 is released), the
92 tree for ``net-next`` reopens to collect conte 93 tree for ``net-next`` reopens to collect content for the next (vX.Y+1)
93 release. 94 release.
94 95
95 If you aren't subscribed to netdev and/or are 96 If you aren't subscribed to netdev and/or are simply unsure if
96 ``net-next`` has re-opened yet, simply check t 97 ``net-next`` has re-opened yet, simply check the ``net-next`` git
97 repository link above for any new networking-r 98 repository link above for any new networking-related commits. You may
98 also check the following website for the curre 99 also check the following website for the current status:
99 100
100 https://netdev.bots.linux.dev/net-next.html !! 101 http://vger.kernel.org/~davem/net-next.html
101 102
102 The ``net`` tree continues to collect fixes fo 103 The ``net`` tree continues to collect fixes for the vX.Y content, and is
103 fed back to Linus at regular (~weekly) interva 104 fed back to Linus at regular (~weekly) intervals. Meaning that the
104 focus for ``net`` is on stabilization and bug 105 focus for ``net`` is on stabilization and bug fixes.
105 106
106 Finally, the vX.Y gets released, and the whole 107 Finally, the vX.Y gets released, and the whole cycle starts over.
107 108
108 netdev patch review 109 netdev patch review
109 ------------------- 110 -------------------
110 111
111 .. _patch_status: 112 .. _patch_status:
112 113
113 Patch status 114 Patch status
114 ~~~~~~~~~~~~ 115 ~~~~~~~~~~~~
115 116
116 Status of a patch can be checked by looking at 117 Status of a patch can be checked by looking at the main patchwork
117 queue for netdev: 118 queue for netdev:
118 119
119 https://patchwork.kernel.org/project/netdevb 120 https://patchwork.kernel.org/project/netdevbpf/list/
120 121
121 The "State" field will tell you exactly where 122 The "State" field will tell you exactly where things are at with your
122 patch: !! 123 patch. Patches are indexed by the ``Message-ID`` header of the emails
123 <<
124 ================== =========================== <<
125 Patch state Description <<
126 ================== =========================== <<
127 New, Under review pending review, patch is in <<
128 review; the two states are <<
129 the exact co-maintainer han <<
130 Accepted patch was applied to the ap <<
131 usually set automatically b <<
132 Needs ACK waiting for an ack from an <<
133 Changes requested patch has not passed the re <<
134 with appropriate code and c <<
135 Rejected patch has been rejected and <<
136 Not applicable patch is expected to be app <<
137 subsystem <<
138 Awaiting upstream patch should be reviewed an <<
139 sub-maintainer, who will se <<
140 patches set to ``Awaiting u <<
141 will usually remain in this <<
142 requested changes, accepted <<
143 Deferred patch needs to be reposted <<
144 or because it was posted fo <<
145 Superseded new version of the patch wa <<
146 pw-bot <<
147 RFC not to be applied, usually <<
148 pw-bot can automatically se <<
149 on subject tags <<
150 ================== =========================== <<
151 <<
152 Patches are indexed by the ``Message-ID`` head <<
153 which carried them so if you have trouble find 124 which carried them so if you have trouble finding your patch append
154 the value of ``Message-ID`` to the URL above. 125 the value of ``Message-ID`` to the URL above.
155 126
156 Updating patch status 127 Updating patch status
157 ~~~~~~~~~~~~~~~~~~~~~ 128 ~~~~~~~~~~~~~~~~~~~~~
158 129
159 Contributors and reviewers do not have the per 130 Contributors and reviewers do not have the permissions to update patch
160 state directly in patchwork. Patchwork doesn't 131 state directly in patchwork. Patchwork doesn't expose much information
161 about the history of the state of patches, the 132 about the history of the state of patches, therefore having multiple
162 people update the state leads to confusion. 133 people update the state leads to confusion.
163 134
164 Instead of delegating patchwork permissions ne 135 Instead of delegating patchwork permissions netdev uses a simple mail
165 bot which looks for special commands/lines wit 136 bot which looks for special commands/lines within the emails sent to
166 the mailing list. For example to mark a series 137 the mailing list. For example to mark a series as Changes Requested
167 one needs to send the following line anywhere 138 one needs to send the following line anywhere in the email thread::
168 139
169 pw-bot: changes-requested 140 pw-bot: changes-requested
170 141
171 As a result the bot will set the entire series 142 As a result the bot will set the entire series to Changes Requested.
172 This may be useful when author discovers a bug 143 This may be useful when author discovers a bug in their own series
173 and wants to prevent it from getting applied. 144 and wants to prevent it from getting applied.
174 145
175 The use of the bot is entirely optional, if in 146 The use of the bot is entirely optional, if in doubt ignore its existence
176 completely. Maintainers will classify and upda 147 completely. Maintainers will classify and update the state of the patches
177 themselves. No email should ever be sent to th 148 themselves. No email should ever be sent to the list with the main purpose
178 of communicating with the bot, the bot command 149 of communicating with the bot, the bot commands should be seen as metadata.
179 150
180 The use of the bot is restricted to authors of 151 The use of the bot is restricted to authors of the patches (the ``From:``
181 header on patch submission and command must ma !! 152 header on patch submission and command must match!), maintainers themselves
182 the modified code according to the MAINTAINERS !! 153 and a handful of senior reviewers. Bot records its activity here:
183 must match the MAINTAINERS entry) and a handfu <<
184 154
185 Bot records its activity here: !! 155 https://patchwork.hopto.org/pw-bot.html
186 <<
187 https://netdev.bots.linux.dev/pw-bot.html <<
188 156
189 Review timelines 157 Review timelines
190 ~~~~~~~~~~~~~~~~ 158 ~~~~~~~~~~~~~~~~
191 159
192 Generally speaking, the patches get triaged qu 160 Generally speaking, the patches get triaged quickly (in less than
193 48h). But be patient, if your patch is active 161 48h). But be patient, if your patch is active in patchwork (i.e. it's
194 listed on the project's patch list) the chance 162 listed on the project's patch list) the chances it was missed are close to zero.
195 !! 163 Asking the maintainer for status updates on your
196 The high volume of development on netdev makes !! 164 patch is a good way to ensure your patch is ignored or pushed to the
197 from discussions relatively quickly. New comme !! 165 bottom of the priority list.
198 are very unlikely to arrive after a week of si <<
199 is no longer active in patchwork and the threa <<
200 than a week - clarify the next steps and/or po <<
201 <<
202 For RFC postings specifically, if nobody respo <<
203 either missed the posting or have no strong op <<
204 repost as a PATCH. <<
205 <<
206 Emails saying just "ping" or "bump" are consid <<
207 out the status of the patch from patchwork or <<
208 landed - describe your best guess and ask if i <<
209 <<
210 I don't understand what the next steps are. <<
211 with A, should I do B and repost the patches <<
212 <<
213 .. _Changes requested: <<
214 166
215 Changes requested 167 Changes requested
216 ~~~~~~~~~~~~~~~~~ 168 ~~~~~~~~~~~~~~~~~
217 169
218 Patches :ref:`marked<patch_status>` as ``Chang 170 Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
219 to be revised. The new version should come wit 171 to be revised. The new version should come with a change log,
220 preferably including links to previous posting 172 preferably including links to previous postings, for example::
221 173
222 [PATCH net-next v3] net: make cows go moo 174 [PATCH net-next v3] net: make cows go moo
223 175
224 Even users who don't drink milk appreciate h 176 Even users who don't drink milk appreciate hearing the cows go "moo".
225 177
226 The amount of mooing will depend on packet r 178 The amount of mooing will depend on packet rate so should match
227 the diurnal cycle quite well. 179 the diurnal cycle quite well.
228 180
229 Signed-off-by: Joe Defarmer <joe@barn.org> !! 181 Signed-of-by: Joe Defarmer <joe@barn.org>
230 --- 182 ---
231 v3: 183 v3:
232 - add a note about time-of-day mooing fluc 184 - add a note about time-of-day mooing fluctuation to the commit message
233 v2: https://lore.kernel.org/netdev/123themes 185 v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
234 - fix missing argument in kernel doc for n 186 - fix missing argument in kernel doc for netif_is_bovine()
235 - fix memory leak in netdev_register_cow() 187 - fix memory leak in netdev_register_cow()
236 v1: https://lore.kernel.org/netdev/456getsth 188 v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/
237 189
238 The commit message should be revised to answer 190 The commit message should be revised to answer any questions reviewers
239 had to ask in previous discussions. Occasional 191 had to ask in previous discussions. Occasionally the update of
240 the commit message will be the only change in 192 the commit message will be the only change in the new version.
241 193
242 Partial resends 194 Partial resends
243 ~~~~~~~~~~~~~~~ 195 ~~~~~~~~~~~~~~~
244 196
245 Please always resend the entire patch series a 197 Please always resend the entire patch series and make sure you do number your
246 patches such that it is clear this is the late 198 patches such that it is clear this is the latest and greatest set of patches
247 that can be applied. Do not try to resend just 199 that can be applied. Do not try to resend just the patches which changed.
248 200
249 Handling misapplied patches 201 Handling misapplied patches
250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 202 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
251 203
252 Occasionally a patch series gets applied befor 204 Occasionally a patch series gets applied before receiving critical feedback,
253 or the wrong version of a series gets applied. 205 or the wrong version of a series gets applied.
254 206
255 Making the patch disappear once it is pushed o 207 Making the patch disappear once it is pushed out is not possible, the commit
256 history in netdev trees is immutable. 208 history in netdev trees is immutable.
257 Please send incremental versions on top of wha 209 Please send incremental versions on top of what has been merged in order to fix
258 the patches the way they would look like if yo 210 the patches the way they would look like if your latest patch series was to be
259 merged. 211 merged.
260 212
261 In cases where full revert is needed the rever 213 In cases where full revert is needed the revert has to be submitted
262 as a patch to the list with a commit message e 214 as a patch to the list with a commit message explaining the technical
263 problems with the reverted commit. Reverts sho 215 problems with the reverted commit. Reverts should be used as a last resort,
264 when original change is completely wrong; incr 216 when original change is completely wrong; incremental fixes are preferred.
265 217
266 Stable tree 218 Stable tree
267 ~~~~~~~~~~~ 219 ~~~~~~~~~~~
268 220
269 While it used to be the case that netdev submi 221 While it used to be the case that netdev submissions were not supposed
270 to carry explicit ``CC: stable@vger.kernel.org 222 to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
271 the case today. Please follow the standard sta 223 the case today. Please follow the standard stable rules in
272 :ref:`Documentation/process/stable-kernel-rule 224 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
273 and make sure you include appropriate Fixes ta 225 and make sure you include appropriate Fixes tags!
274 226
275 Security fixes 227 Security fixes
276 ~~~~~~~~~~~~~~ 228 ~~~~~~~~~~~~~~
277 229
278 Do not email netdev maintainers directly if yo 230 Do not email netdev maintainers directly if you think you discovered
279 a bug that might have possible security implic 231 a bug that might have possible security implications.
280 The current netdev maintainer has consistently 232 The current netdev maintainer has consistently requested that
281 people use the mailing lists and not reach out 233 people use the mailing lists and not reach out directly. If you aren't
282 OK with that, then perhaps consider mailing se 234 OK with that, then perhaps consider mailing security@kernel.org or
283 reading about http://oss-security.openwall.org 235 reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
284 as possible alternative mechanisms. 236 as possible alternative mechanisms.
285 237
286 238
287 Co-posting changes to user space components 239 Co-posting changes to user space components
288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 240 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
289 241
290 User space code exercising kernel features sho 242 User space code exercising kernel features should be posted
291 alongside kernel patches. This gives reviewers 243 alongside kernel patches. This gives reviewers a chance to see
292 how any new interface is used and how well it 244 how any new interface is used and how well it works.
293 245
294 When user space tools reside in the kernel rep 246 When user space tools reside in the kernel repo itself all changes
295 should generally come as one series. If series 247 should generally come as one series. If series becomes too large
296 or the user space project is not reviewed on n 248 or the user space project is not reviewed on netdev include a link
297 to a public repo where user space patches can 249 to a public repo where user space patches can be seen.
298 250
299 In case user space tooling lives in a separate 251 In case user space tooling lives in a separate repository but is
300 reviewed on netdev (e.g. patches to ``iproute 252 reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and
301 user space patches should form separate series 253 user space patches should form separate series (threads) when posted
302 to the mailing list, e.g.:: 254 to the mailing list, e.g.::
303 255
304 [PATCH net-next 0/3] net: some feature cover 256 [PATCH net-next 0/3] net: some feature cover letter
305 └─ [PATCH net-next 1/3] net: some featu 257 └─ [PATCH net-next 1/3] net: some feature prep
306 └─ [PATCH net-next 2/3] net: some featu 258 └─ [PATCH net-next 2/3] net: some feature do it
307 └─ [PATCH net-next 3/3] selftest: net: 259 └─ [PATCH net-next 3/3] selftest: net: some feature
308 260
309 [PATCH iproute2-next] ip: add support for so 261 [PATCH iproute2-next] ip: add support for some feature
310 262
311 Posting as one thread is discouraged because i 263 Posting as one thread is discouraged because it confuses patchwork
312 (as of patchwork 2.2.2). 264 (as of patchwork 2.2.2).
313 265
314 Preparing changes 266 Preparing changes
315 ----------------- 267 -----------------
316 268
317 Attention to detail is important. Re-read you 269 Attention to detail is important. Re-read your own work as if you were the
318 reviewer. You can start with using ``checkpat 270 reviewer. You can start with using ``checkpatch.pl``, perhaps even with
319 the ``--strict`` flag. But do not be mindless 271 the ``--strict`` flag. But do not be mindlessly robotic in doing so.
320 If your change is a bug fix, make sure your co 272 If your change is a bug fix, make sure your commit log indicates the
321 end-user visible symptom, the underlying reaso 273 end-user visible symptom, the underlying reason as to why it happens,
322 and then if necessary, explain why the fix pro 274 and then if necessary, explain why the fix proposed is the best way to
323 get things done. Don't mangle whitespace, and 275 get things done. Don't mangle whitespace, and as is common, don't
324 mis-indent function arguments that span multip 276 mis-indent function arguments that span multiple lines. If it is your
325 first patch, mail it to yourself so you can te 277 first patch, mail it to yourself so you can test apply it to an
326 unpatched tree to confirm infrastructure didn' 278 unpatched tree to confirm infrastructure didn't mangle it.
327 279
328 Finally, go back and read 280 Finally, go back and read
329 :ref:`Documentation/process/submitting-patches 281 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
330 to be sure you are not repeating some common m 282 to be sure you are not repeating some common mistake documented there.
331 283
332 Indicating target tree 284 Indicating target tree
333 ~~~~~~~~~~~~~~~~~~~~~~ 285 ~~~~~~~~~~~~~~~~~~~~~~
334 286
335 To help maintainers and CI bots you should exp 287 To help maintainers and CI bots you should explicitly mark which tree
336 your patch is targeting. Assuming that you use 288 your patch is targeting. Assuming that you use git, use the prefix
337 flag:: 289 flag::
338 290
339 git format-patch --subject-prefix='PATCH net 291 git format-patch --subject-prefix='PATCH net-next' start..finish
340 292
341 Use ``net`` instead of ``net-next`` (always lo 293 Use ``net`` instead of ``net-next`` (always lower case) in the above for
342 bug-fix ``net`` content. 294 bug-fix ``net`` content.
343 295
344 Dividing work into patches 296 Dividing work into patches
345 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 297 ~~~~~~~~~~~~~~~~~~~~~~~~~~
346 298
347 Put yourself in the shoes of the reviewer. Eac 299 Put yourself in the shoes of the reviewer. Each patch is read separately
348 and therefore should constitute a comprehensib 300 and therefore should constitute a comprehensible step towards your stated
349 goal. 301 goal.
350 302
351 Avoid sending series longer than 15 patches. L 303 Avoid sending series longer than 15 patches. Larger series takes longer
352 to review as reviewers will defer looking at i 304 to review as reviewers will defer looking at it until they find a large
353 chunk of time. A small series can be reviewed 305 chunk of time. A small series can be reviewed in a short time, so Maintainers
354 just do it. As a result, a sequence of smaller 306 just do it. As a result, a sequence of smaller series gets merged quicker and
355 with better review coverage. Re-posting large 307 with better review coverage. Re-posting large series also increases the mailing
356 list traffic. 308 list traffic.
357 309
>> 310 Multi-line comments
>> 311 ~~~~~~~~~~~~~~~~~~~
>> 312
>> 313 Comment style convention is slightly different for networking and most of
>> 314 the tree. Instead of this::
>> 315
>> 316 /*
>> 317 * foobar blah blah blah
>> 318 * another line of text
>> 319 */
>> 320
>> 321 it is requested that you make it look like this::
>> 322
>> 323 /* foobar blah blah blah
>> 324 * another line of text
>> 325 */
>> 326
358 Local variable ordering ("reverse xmas tree", 327 Local variable ordering ("reverse xmas tree", "RCS")
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 328 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
360 329
361 Netdev has a convention for ordering local var 330 Netdev has a convention for ordering local variables in functions.
362 Order the variable declaration lines longest t 331 Order the variable declaration lines longest to shortest, e.g.::
363 332
364 struct scatterlist *sg; 333 struct scatterlist *sg;
365 struct sk_buff *skb; 334 struct sk_buff *skb;
366 int err, i; 335 int err, i;
367 336
368 If there are dependencies between the variable 337 If there are dependencies between the variables preventing the ordering
369 move the initialization out of line. 338 move the initialization out of line.
370 339
371 Format precedence 340 Format precedence
372 ~~~~~~~~~~~~~~~~~ 341 ~~~~~~~~~~~~~~~~~
373 342
374 When working in existing code which uses nonst 343 When working in existing code which uses nonstandard formatting make
375 your code follow the most recent guidelines, s 344 your code follow the most recent guidelines, so that eventually all code
376 in the domain of netdev is in the preferred fo 345 in the domain of netdev is in the preferred format.
377 346
378 Using device-managed and cleanup.h constructs <<
379 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ <<
380 <<
381 Netdev remains skeptical about promises of all <<
382 including even ``devm_`` helpers, historically <<
383 style of implementation, merely an acceptable <<
384 <<
385 Use of ``guard()`` is discouraged within any f <<
386 ``scoped_guard()`` is considered more readable <<
387 still (weakly) preferred. <<
388 <<
389 Low level cleanup constructs (such as ``__free <<
390 APIs and helpers, especially scoped iterators. <<
391 ``__free()`` within networking core and driver <<
392 Similar guidance applies to declaring variable <<
393 <<
394 Resending after review 347 Resending after review
395 ~~~~~~~~~~~~~~~~~~~~~~ 348 ~~~~~~~~~~~~~~~~~~~~~~
396 349
397 Allow at least 24 hours to pass between postin 350 Allow at least 24 hours to pass between postings. This will ensure reviewers
398 from all geographical locations have a chance 351 from all geographical locations have a chance to chime in. Do not wait
399 too long (weeks) between postings either as it 352 too long (weeks) between postings either as it will make it harder for reviewers
400 to recall all the context. 353 to recall all the context.
401 354
402 Make sure you address all the feedback in your 355 Make sure you address all the feedback in your new posting. Do not post a new
403 version of the code if the discussion about th 356 version of the code if the discussion about the previous version is still
404 ongoing, unless directly instructed by a revie 357 ongoing, unless directly instructed by a reviewer.
405 358
406 The new version of patches should be posted as <<
407 not as a reply to the previous posting. Change <<
408 to the previous posting (see :ref:`Changes req <<
409 <<
410 Testing 359 Testing
411 ------- 360 -------
412 361
413 Expected level of testing 362 Expected level of testing
414 ~~~~~~~~~~~~~~~~~~~~~~~~~ 363 ~~~~~~~~~~~~~~~~~~~~~~~~~
415 364
416 At the very minimum your changes must survive 365 At the very minimum your changes must survive an ``allyesconfig`` and an
417 ``allmodconfig`` build with ``W=1`` set withou 366 ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
418 367
419 Ideally you will have done run-time testing sp 368 Ideally you will have done run-time testing specific to your change,
420 and the patch series contains a set of kernel 369 and the patch series contains a set of kernel selftest for
421 ``tools/testing/selftests/net`` or using the K 370 ``tools/testing/selftests/net`` or using the KUnit framework.
422 371
423 You are expected to test your changes on top o 372 You are expected to test your changes on top of the relevant networking
424 tree (``net`` or ``net-next``) and not e.g. a 373 tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
425 374
426 patchwork checks 375 patchwork checks
427 ~~~~~~~~~~~~~~~~ 376 ~~~~~~~~~~~~~~~~
428 377
429 Checks in patchwork are mostly simple wrappers 378 Checks in patchwork are mostly simple wrappers around existing kernel
430 scripts, the sources are available at: 379 scripts, the sources are available at:
431 380
432 https://github.com/linux-netdev/nipa/tree/mast !! 381 https://github.com/kuba-moo/nipa/tree/master/tests
433 382
434 **Do not** post your patches just to run them 383 **Do not** post your patches just to run them through the checks.
435 You must ensure that your patches are ready by 384 You must ensure that your patches are ready by testing them locally
436 before posting to the mailing list. The patchw 385 before posting to the mailing list. The patchwork build bot instance
437 gets overloaded very easily and netdev@vger re 386 gets overloaded very easily and netdev@vger really doesn't need more
438 traffic if we can help it. 387 traffic if we can help it.
439 388
440 netdevsim 389 netdevsim
441 ~~~~~~~~~ 390 ~~~~~~~~~
442 391
443 ``netdevsim`` is a test driver which can be us 392 ``netdevsim`` is a test driver which can be used to exercise driver
444 configuration APIs without requiring capable h 393 configuration APIs without requiring capable hardware.
445 Mock-ups and tests based on ``netdevsim`` are 394 Mock-ups and tests based on ``netdevsim`` are strongly encouraged when
446 adding new APIs, but ``netdevsim`` in itself i 395 adding new APIs, but ``netdevsim`` in itself is **not** considered
447 a use case/user. You must also implement the n 396 a use case/user. You must also implement the new APIs in a real driver.
448 397
449 We give no guarantees that ``netdevsim`` won't 398 We give no guarantees that ``netdevsim`` won't change in the future
450 in a way which would break what would normally 399 in a way which would break what would normally be considered uAPI.
451 400
452 ``netdevsim`` is reserved for use by upstream 401 ``netdevsim`` is reserved for use by upstream tests only, so any
453 new ``netdevsim`` features must be accompanied 402 new ``netdevsim`` features must be accompanied by selftests under
454 ``tools/testing/selftests/``. 403 ``tools/testing/selftests/``.
455 <<
456 Reviewer guidance <<
457 ----------------- <<
458 <<
459 Reviewing other people's patches on the list i <<
460 regardless of the level of expertise. For gene <<
461 helpful tips please see :ref:`development_adva <<
462 <<
463 It's safe to assume that netdev maintainers kn <<
464 of expertise of the reviewers. The reviewers s <<
465 their comments impeding or derailing the patch <<
466 <<
467 Less experienced reviewers are highly encourag <<
468 review of submissions and not focus exclusivel <<
469 matters like code formatting, tags etc. <<
470 404
471 Testimonials / feedback 405 Testimonials / feedback
472 ----------------------- 406 -----------------------
473 407
474 Some companies use peer feedback in employee p 408 Some companies use peer feedback in employee performance reviews.
475 Please feel free to request feedback from netd 409 Please feel free to request feedback from netdev maintainers,
476 especially if you spend significant amount of 410 especially if you spend significant amount of time reviewing code
477 and go out of your way to improve shared infra 411 and go out of your way to improve shared infrastructure.
478 412
479 The feedback must be requested by you, the con 413 The feedback must be requested by you, the contributor, and will always
480 be shared with you (even if you request for it 414 be shared with you (even if you request for it to be submitted to your
481 manager). 415 manager).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.