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 https://netdev.bots.linux.dev/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:
123 124
124 ================== =========================== 125 ================== =============================================================
125 Patch state Description 126 Patch state Description
126 ================== =========================== 127 ================== =============================================================
127 New, Under review pending review, patch is in 128 New, Under review pending review, patch is in the maintainer’s queue for
128 review; the two states are 129 review; the two states are used interchangeably (depending on
129 the exact co-maintainer han 130 the exact co-maintainer handling patchwork at the time)
130 Accepted patch was applied to the ap 131 Accepted patch was applied to the appropriate networking tree, this is
131 usually set automatically b 132 usually set automatically by the pw-bot
132 Needs ACK waiting for an ack from an 133 Needs ACK waiting for an ack from an area expert or testing
133 Changes requested patch has not passed the re 134 Changes requested patch has not passed the review, new revision is expected
134 with appropriate code and c 135 with appropriate code and commit message changes
135 Rejected patch has been rejected and 136 Rejected patch has been rejected and new revision is not expected
136 Not applicable patch is expected to be app 137 Not applicable patch is expected to be applied outside of the networking
137 subsystem 138 subsystem
138 Awaiting upstream patch should be reviewed an 139 Awaiting upstream patch should be reviewed and handled by appropriate
139 sub-maintainer, who will se 140 sub-maintainer, who will send it on to the networking trees;
140 patches set to ``Awaiting u 141 patches set to ``Awaiting upstream`` in netdev's patchwork
141 will usually remain in this 142 will usually remain in this state, whether the sub-maintainer
142 requested changes, accepted 143 requested changes, accepted or rejected the patch
143 Deferred patch needs to be reposted 144 Deferred patch needs to be reposted later, usually due to dependency
144 or because it was posted fo 145 or because it was posted for a closed tree
145 Superseded new version of the patch wa 146 Superseded new version of the patch was posted, usually set by the
146 pw-bot 147 pw-bot
147 RFC not to be applied, usually 148 RFC not to be applied, usually not in maintainer’s review queue,
148 pw-bot can automatically se 149 pw-bot can automatically set patches to this state based
149 on subject tags 150 on subject tags
150 ================== =========================== 151 ================== =============================================================
151 152
152 Patches are indexed by the ``Message-ID`` head 153 Patches are indexed by the ``Message-ID`` header of the emails
153 which carried them so if you have trouble find 154 which carried them so if you have trouble finding your patch append
154 the value of ``Message-ID`` to the URL above. 155 the value of ``Message-ID`` to the URL above.
155 156
156 Updating patch status 157 Updating patch status
157 ~~~~~~~~~~~~~~~~~~~~~ 158 ~~~~~~~~~~~~~~~~~~~~~
158 159
159 Contributors and reviewers do not have the per 160 Contributors and reviewers do not have the permissions to update patch
160 state directly in patchwork. Patchwork doesn't 161 state directly in patchwork. Patchwork doesn't expose much information
161 about the history of the state of patches, the 162 about the history of the state of patches, therefore having multiple
162 people update the state leads to confusion. 163 people update the state leads to confusion.
163 164
164 Instead of delegating patchwork permissions ne 165 Instead of delegating patchwork permissions netdev uses a simple mail
165 bot which looks for special commands/lines wit 166 bot which looks for special commands/lines within the emails sent to
166 the mailing list. For example to mark a series 167 the mailing list. For example to mark a series as Changes Requested
167 one needs to send the following line anywhere 168 one needs to send the following line anywhere in the email thread::
168 169
169 pw-bot: changes-requested 170 pw-bot: changes-requested
170 171
171 As a result the bot will set the entire series 172 As a result the bot will set the entire series to Changes Requested.
172 This may be useful when author discovers a bug 173 This may be useful when author discovers a bug in their own series
173 and wants to prevent it from getting applied. 174 and wants to prevent it from getting applied.
174 175
175 The use of the bot is entirely optional, if in 176 The use of the bot is entirely optional, if in doubt ignore its existence
176 completely. Maintainers will classify and upda 177 completely. Maintainers will classify and update the state of the patches
177 themselves. No email should ever be sent to th 178 themselves. No email should ever be sent to the list with the main purpose
178 of communicating with the bot, the bot command 179 of communicating with the bot, the bot commands should be seen as metadata.
179 180
180 The use of the bot is restricted to authors of 181 The use of the bot is restricted to authors of the patches (the ``From:``
181 header on patch submission and command must ma 182 header on patch submission and command must match!), maintainers of
182 the modified code according to the MAINTAINERS 183 the modified code according to the MAINTAINERS file (again, ``From:``
183 must match the MAINTAINERS entry) and a handfu 184 must match the MAINTAINERS entry) and a handful of senior reviewers.
184 185
185 Bot records its activity here: 186 Bot records its activity here:
186 187
187 https://netdev.bots.linux.dev/pw-bot.html 188 https://netdev.bots.linux.dev/pw-bot.html
188 189
189 Review timelines 190 Review timelines
190 ~~~~~~~~~~~~~~~~ 191 ~~~~~~~~~~~~~~~~
191 192
192 Generally speaking, the patches get triaged qu 193 Generally speaking, the patches get triaged quickly (in less than
193 48h). But be patient, if your patch is active 194 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 195 listed on the project's patch list) the chances it was missed are close to zero.
195 !! 196 Asking the maintainer for status updates on your
196 The high volume of development on netdev makes !! 197 patch is a good way to ensure your patch is ignored or pushed to the
197 from discussions relatively quickly. New comme !! 198 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 199
213 .. _Changes requested: 200 .. _Changes requested:
214 201
215 Changes requested 202 Changes requested
216 ~~~~~~~~~~~~~~~~~ 203 ~~~~~~~~~~~~~~~~~
217 204
218 Patches :ref:`marked<patch_status>` as ``Chang 205 Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
219 to be revised. The new version should come wit 206 to be revised. The new version should come with a change log,
220 preferably including links to previous posting 207 preferably including links to previous postings, for example::
221 208
222 [PATCH net-next v3] net: make cows go moo 209 [PATCH net-next v3] net: make cows go moo
223 210
224 Even users who don't drink milk appreciate h 211 Even users who don't drink milk appreciate hearing the cows go "moo".
225 212
226 The amount of mooing will depend on packet r 213 The amount of mooing will depend on packet rate so should match
227 the diurnal cycle quite well. 214 the diurnal cycle quite well.
228 215
229 Signed-off-by: Joe Defarmer <joe@barn.org> !! 216 Signed-of-by: Joe Defarmer <joe@barn.org>
230 --- 217 ---
231 v3: 218 v3:
232 - add a note about time-of-day mooing fluc 219 - add a note about time-of-day mooing fluctuation to the commit message
233 v2: https://lore.kernel.org/netdev/123themes 220 v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
234 - fix missing argument in kernel doc for n 221 - fix missing argument in kernel doc for netif_is_bovine()
235 - fix memory leak in netdev_register_cow() 222 - fix memory leak in netdev_register_cow()
236 v1: https://lore.kernel.org/netdev/456getsth 223 v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/
237 224
238 The commit message should be revised to answer 225 The commit message should be revised to answer any questions reviewers
239 had to ask in previous discussions. Occasional 226 had to ask in previous discussions. Occasionally the update of
240 the commit message will be the only change in 227 the commit message will be the only change in the new version.
241 228
242 Partial resends 229 Partial resends
243 ~~~~~~~~~~~~~~~ 230 ~~~~~~~~~~~~~~~
244 231
245 Please always resend the entire patch series a 232 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 233 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 234 that can be applied. Do not try to resend just the patches which changed.
248 235
249 Handling misapplied patches 236 Handling misapplied patches
250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 237 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
251 238
252 Occasionally a patch series gets applied befor 239 Occasionally a patch series gets applied before receiving critical feedback,
253 or the wrong version of a series gets applied. 240 or the wrong version of a series gets applied.
254 241
255 Making the patch disappear once it is pushed o 242 Making the patch disappear once it is pushed out is not possible, the commit
256 history in netdev trees is immutable. 243 history in netdev trees is immutable.
257 Please send incremental versions on top of wha 244 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 245 the patches the way they would look like if your latest patch series was to be
259 merged. 246 merged.
260 247
261 In cases where full revert is needed the rever 248 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 249 as a patch to the list with a commit message explaining the technical
263 problems with the reverted commit. Reverts sho 250 problems with the reverted commit. Reverts should be used as a last resort,
264 when original change is completely wrong; incr 251 when original change is completely wrong; incremental fixes are preferred.
265 252
266 Stable tree 253 Stable tree
267 ~~~~~~~~~~~ 254 ~~~~~~~~~~~
268 255
269 While it used to be the case that netdev submi 256 While it used to be the case that netdev submissions were not supposed
270 to carry explicit ``CC: stable@vger.kernel.org 257 to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
271 the case today. Please follow the standard sta 258 the case today. Please follow the standard stable rules in
272 :ref:`Documentation/process/stable-kernel-rule 259 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
273 and make sure you include appropriate Fixes ta 260 and make sure you include appropriate Fixes tags!
274 261
275 Security fixes 262 Security fixes
276 ~~~~~~~~~~~~~~ 263 ~~~~~~~~~~~~~~
277 264
278 Do not email netdev maintainers directly if yo 265 Do not email netdev maintainers directly if you think you discovered
279 a bug that might have possible security implic 266 a bug that might have possible security implications.
280 The current netdev maintainer has consistently 267 The current netdev maintainer has consistently requested that
281 people use the mailing lists and not reach out 268 people use the mailing lists and not reach out directly. If you aren't
282 OK with that, then perhaps consider mailing se 269 OK with that, then perhaps consider mailing security@kernel.org or
283 reading about http://oss-security.openwall.org 270 reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
284 as possible alternative mechanisms. 271 as possible alternative mechanisms.
285 272
286 273
287 Co-posting changes to user space components 274 Co-posting changes to user space components
288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 275 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
289 276
290 User space code exercising kernel features sho 277 User space code exercising kernel features should be posted
291 alongside kernel patches. This gives reviewers 278 alongside kernel patches. This gives reviewers a chance to see
292 how any new interface is used and how well it 279 how any new interface is used and how well it works.
293 280
294 When user space tools reside in the kernel rep 281 When user space tools reside in the kernel repo itself all changes
295 should generally come as one series. If series 282 should generally come as one series. If series becomes too large
296 or the user space project is not reviewed on n 283 or the user space project is not reviewed on netdev include a link
297 to a public repo where user space patches can 284 to a public repo where user space patches can be seen.
298 285
299 In case user space tooling lives in a separate 286 In case user space tooling lives in a separate repository but is
300 reviewed on netdev (e.g. patches to ``iproute 287 reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and
301 user space patches should form separate series 288 user space patches should form separate series (threads) when posted
302 to the mailing list, e.g.:: 289 to the mailing list, e.g.::
303 290
304 [PATCH net-next 0/3] net: some feature cover 291 [PATCH net-next 0/3] net: some feature cover letter
305 └─ [PATCH net-next 1/3] net: some featu 292 └─ [PATCH net-next 1/3] net: some feature prep
306 └─ [PATCH net-next 2/3] net: some featu 293 └─ [PATCH net-next 2/3] net: some feature do it
307 └─ [PATCH net-next 3/3] selftest: net: 294 └─ [PATCH net-next 3/3] selftest: net: some feature
308 295
309 [PATCH iproute2-next] ip: add support for so 296 [PATCH iproute2-next] ip: add support for some feature
310 297
311 Posting as one thread is discouraged because i 298 Posting as one thread is discouraged because it confuses patchwork
312 (as of patchwork 2.2.2). 299 (as of patchwork 2.2.2).
313 300
314 Preparing changes 301 Preparing changes
315 ----------------- 302 -----------------
316 303
317 Attention to detail is important. Re-read you 304 Attention to detail is important. Re-read your own work as if you were the
318 reviewer. You can start with using ``checkpat 305 reviewer. You can start with using ``checkpatch.pl``, perhaps even with
319 the ``--strict`` flag. But do not be mindless 306 the ``--strict`` flag. But do not be mindlessly robotic in doing so.
320 If your change is a bug fix, make sure your co 307 If your change is a bug fix, make sure your commit log indicates the
321 end-user visible symptom, the underlying reaso 308 end-user visible symptom, the underlying reason as to why it happens,
322 and then if necessary, explain why the fix pro 309 and then if necessary, explain why the fix proposed is the best way to
323 get things done. Don't mangle whitespace, and 310 get things done. Don't mangle whitespace, and as is common, don't
324 mis-indent function arguments that span multip 311 mis-indent function arguments that span multiple lines. If it is your
325 first patch, mail it to yourself so you can te 312 first patch, mail it to yourself so you can test apply it to an
326 unpatched tree to confirm infrastructure didn' 313 unpatched tree to confirm infrastructure didn't mangle it.
327 314
328 Finally, go back and read 315 Finally, go back and read
329 :ref:`Documentation/process/submitting-patches 316 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
330 to be sure you are not repeating some common m 317 to be sure you are not repeating some common mistake documented there.
331 318
332 Indicating target tree 319 Indicating target tree
333 ~~~~~~~~~~~~~~~~~~~~~~ 320 ~~~~~~~~~~~~~~~~~~~~~~
334 321
335 To help maintainers and CI bots you should exp 322 To help maintainers and CI bots you should explicitly mark which tree
336 your patch is targeting. Assuming that you use 323 your patch is targeting. Assuming that you use git, use the prefix
337 flag:: 324 flag::
338 325
339 git format-patch --subject-prefix='PATCH net 326 git format-patch --subject-prefix='PATCH net-next' start..finish
340 327
341 Use ``net`` instead of ``net-next`` (always lo 328 Use ``net`` instead of ``net-next`` (always lower case) in the above for
342 bug-fix ``net`` content. 329 bug-fix ``net`` content.
343 330
344 Dividing work into patches 331 Dividing work into patches
345 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 332 ~~~~~~~~~~~~~~~~~~~~~~~~~~
346 333
347 Put yourself in the shoes of the reviewer. Eac 334 Put yourself in the shoes of the reviewer. Each patch is read separately
348 and therefore should constitute a comprehensib 335 and therefore should constitute a comprehensible step towards your stated
349 goal. 336 goal.
350 337
351 Avoid sending series longer than 15 patches. L 338 Avoid sending series longer than 15 patches. Larger series takes longer
352 to review as reviewers will defer looking at i 339 to review as reviewers will defer looking at it until they find a large
353 chunk of time. A small series can be reviewed 340 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 341 just do it. As a result, a sequence of smaller series gets merged quicker and
355 with better review coverage. Re-posting large 342 with better review coverage. Re-posting large series also increases the mailing
356 list traffic. 343 list traffic.
357 344
>> 345 Multi-line comments
>> 346 ~~~~~~~~~~~~~~~~~~~
>> 347
>> 348 Comment style convention is slightly different for networking and most of
>> 349 the tree. Instead of this::
>> 350
>> 351 /*
>> 352 * foobar blah blah blah
>> 353 * another line of text
>> 354 */
>> 355
>> 356 it is requested that you make it look like this::
>> 357
>> 358 /* foobar blah blah blah
>> 359 * another line of text
>> 360 */
>> 361
358 Local variable ordering ("reverse xmas tree", 362 Local variable ordering ("reverse xmas tree", "RCS")
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 363 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
360 364
361 Netdev has a convention for ordering local var 365 Netdev has a convention for ordering local variables in functions.
362 Order the variable declaration lines longest t 366 Order the variable declaration lines longest to shortest, e.g.::
363 367
364 struct scatterlist *sg; 368 struct scatterlist *sg;
365 struct sk_buff *skb; 369 struct sk_buff *skb;
366 int err, i; 370 int err, i;
367 371
368 If there are dependencies between the variable 372 If there are dependencies between the variables preventing the ordering
369 move the initialization out of line. 373 move the initialization out of line.
370 374
371 Format precedence 375 Format precedence
372 ~~~~~~~~~~~~~~~~~ 376 ~~~~~~~~~~~~~~~~~
373 377
374 When working in existing code which uses nonst 378 When working in existing code which uses nonstandard formatting make
375 your code follow the most recent guidelines, s 379 your code follow the most recent guidelines, so that eventually all code
376 in the domain of netdev is in the preferred fo 380 in the domain of netdev is in the preferred format.
377 381
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 382 Resending after review
395 ~~~~~~~~~~~~~~~~~~~~~~ 383 ~~~~~~~~~~~~~~~~~~~~~~
396 384
397 Allow at least 24 hours to pass between postin 385 Allow at least 24 hours to pass between postings. This will ensure reviewers
398 from all geographical locations have a chance 386 from all geographical locations have a chance to chime in. Do not wait
399 too long (weeks) between postings either as it 387 too long (weeks) between postings either as it will make it harder for reviewers
400 to recall all the context. 388 to recall all the context.
401 389
402 Make sure you address all the feedback in your 390 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 391 version of the code if the discussion about the previous version is still
404 ongoing, unless directly instructed by a revie 392 ongoing, unless directly instructed by a reviewer.
405 393
406 The new version of patches should be posted as 394 The new version of patches should be posted as a separate thread,
407 not as a reply to the previous posting. Change 395 not as a reply to the previous posting. Change log should include a link
408 to the previous posting (see :ref:`Changes req 396 to the previous posting (see :ref:`Changes requested`).
409 397
410 Testing 398 Testing
411 ------- 399 -------
412 400
413 Expected level of testing 401 Expected level of testing
414 ~~~~~~~~~~~~~~~~~~~~~~~~~ 402 ~~~~~~~~~~~~~~~~~~~~~~~~~
415 403
416 At the very minimum your changes must survive 404 At the very minimum your changes must survive an ``allyesconfig`` and an
417 ``allmodconfig`` build with ``W=1`` set withou 405 ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
418 406
419 Ideally you will have done run-time testing sp 407 Ideally you will have done run-time testing specific to your change,
420 and the patch series contains a set of kernel 408 and the patch series contains a set of kernel selftest for
421 ``tools/testing/selftests/net`` or using the K 409 ``tools/testing/selftests/net`` or using the KUnit framework.
422 410
423 You are expected to test your changes on top o 411 You are expected to test your changes on top of the relevant networking
424 tree (``net`` or ``net-next``) and not e.g. a 412 tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
425 413
426 patchwork checks 414 patchwork checks
427 ~~~~~~~~~~~~~~~~ 415 ~~~~~~~~~~~~~~~~
428 416
429 Checks in patchwork are mostly simple wrappers 417 Checks in patchwork are mostly simple wrappers around existing kernel
430 scripts, the sources are available at: 418 scripts, the sources are available at:
431 419
432 https://github.com/linux-netdev/nipa/tree/mast !! 420 https://github.com/kuba-moo/nipa/tree/master/tests
433 421
434 **Do not** post your patches just to run them 422 **Do not** post your patches just to run them through the checks.
435 You must ensure that your patches are ready by 423 You must ensure that your patches are ready by testing them locally
436 before posting to the mailing list. The patchw 424 before posting to the mailing list. The patchwork build bot instance
437 gets overloaded very easily and netdev@vger re 425 gets overloaded very easily and netdev@vger really doesn't need more
438 traffic if we can help it. 426 traffic if we can help it.
439 427
440 netdevsim 428 netdevsim
441 ~~~~~~~~~ 429 ~~~~~~~~~
442 430
443 ``netdevsim`` is a test driver which can be us 431 ``netdevsim`` is a test driver which can be used to exercise driver
444 configuration APIs without requiring capable h 432 configuration APIs without requiring capable hardware.
445 Mock-ups and tests based on ``netdevsim`` are 433 Mock-ups and tests based on ``netdevsim`` are strongly encouraged when
446 adding new APIs, but ``netdevsim`` in itself i 434 adding new APIs, but ``netdevsim`` in itself is **not** considered
447 a use case/user. You must also implement the n 435 a use case/user. You must also implement the new APIs in a real driver.
448 436
449 We give no guarantees that ``netdevsim`` won't 437 We give no guarantees that ``netdevsim`` won't change in the future
450 in a way which would break what would normally 438 in a way which would break what would normally be considered uAPI.
451 439
452 ``netdevsim`` is reserved for use by upstream 440 ``netdevsim`` is reserved for use by upstream tests only, so any
453 new ``netdevsim`` features must be accompanied 441 new ``netdevsim`` features must be accompanied by selftests under
454 ``tools/testing/selftests/``. 442 ``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 443
471 Testimonials / feedback 444 Testimonials / feedback
472 ----------------------- 445 -----------------------
473 446
474 Some companies use peer feedback in employee p 447 Some companies use peer feedback in employee performance reviews.
475 Please feel free to request feedback from netd 448 Please feel free to request feedback from netdev maintainers,
476 especially if you spend significant amount of 449 especially if you spend significant amount of time reviewing code
477 and go out of your way to improve shared infra 450 and go out of your way to improve shared infrastructure.
478 451
479 The feedback must be requested by you, the con 452 The feedback must be requested by you, the contributor, and will always
480 be shared with you (even if you request for it 453 be shared with you (even if you request for it to be submitted to your
481 manager). 454 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.