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
196 The high volume of development on netdev makes 197 The high volume of development on netdev makes reviewers move on
197 from discussions relatively quickly. New comme 198 from discussions relatively quickly. New comments and replies
198 are very unlikely to arrive after a week of si 199 are very unlikely to arrive after a week of silence. If a patch
199 is no longer active in patchwork and the threa 200 is no longer active in patchwork and the thread went idle for more
200 than a week - clarify the next steps and/or po 201 than a week - clarify the next steps and/or post the next version.
201 202
202 For RFC postings specifically, if nobody respo 203 For RFC postings specifically, if nobody responded in a week - reviewers
203 either missed the posting or have no strong op 204 either missed the posting or have no strong opinions. If the code is ready,
204 repost as a PATCH. 205 repost as a PATCH.
205 206
206 Emails saying just "ping" or "bump" are consid 207 Emails saying just "ping" or "bump" are considered rude. If you can't figure
207 out the status of the patch from patchwork or 208 out the status of the patch from patchwork or where the discussion has
208 landed - describe your best guess and ask if i 209 landed - describe your best guess and ask if it's correct. For example::
209 210
210 I don't understand what the next steps are. 211 I don't understand what the next steps are. Person X seems to be unhappy
211 with A, should I do B and repost the patches 212 with A, should I do B and repost the patches?
212 213
213 .. _Changes requested: 214 .. _Changes requested:
214 215
215 Changes requested 216 Changes requested
216 ~~~~~~~~~~~~~~~~~ 217 ~~~~~~~~~~~~~~~~~
217 218
218 Patches :ref:`marked<patch_status>` as ``Chang 219 Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
219 to be revised. The new version should come wit 220 to be revised. The new version should come with a change log,
220 preferably including links to previous posting 221 preferably including links to previous postings, for example::
221 222
222 [PATCH net-next v3] net: make cows go moo 223 [PATCH net-next v3] net: make cows go moo
223 224
224 Even users who don't drink milk appreciate h 225 Even users who don't drink milk appreciate hearing the cows go "moo".
225 226
226 The amount of mooing will depend on packet r 227 The amount of mooing will depend on packet rate so should match
227 the diurnal cycle quite well. 228 the diurnal cycle quite well.
228 229
229 Signed-off-by: Joe Defarmer <joe@barn.org> !! 230 Signed-of-by: Joe Defarmer <joe@barn.org>
230 --- 231 ---
231 v3: 232 v3:
232 - add a note about time-of-day mooing fluc 233 - add a note about time-of-day mooing fluctuation to the commit message
233 v2: https://lore.kernel.org/netdev/123themes 234 v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
234 - fix missing argument in kernel doc for n 235 - fix missing argument in kernel doc for netif_is_bovine()
235 - fix memory leak in netdev_register_cow() 236 - fix memory leak in netdev_register_cow()
236 v1: https://lore.kernel.org/netdev/456getsth 237 v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/
237 238
238 The commit message should be revised to answer 239 The commit message should be revised to answer any questions reviewers
239 had to ask in previous discussions. Occasional 240 had to ask in previous discussions. Occasionally the update of
240 the commit message will be the only change in 241 the commit message will be the only change in the new version.
241 242
242 Partial resends 243 Partial resends
243 ~~~~~~~~~~~~~~~ 244 ~~~~~~~~~~~~~~~
244 245
245 Please always resend the entire patch series a 246 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 247 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 248 that can be applied. Do not try to resend just the patches which changed.
248 249
249 Handling misapplied patches 250 Handling misapplied patches
250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
251 252
252 Occasionally a patch series gets applied befor 253 Occasionally a patch series gets applied before receiving critical feedback,
253 or the wrong version of a series gets applied. 254 or the wrong version of a series gets applied.
254 255
255 Making the patch disappear once it is pushed o 256 Making the patch disappear once it is pushed out is not possible, the commit
256 history in netdev trees is immutable. 257 history in netdev trees is immutable.
257 Please send incremental versions on top of wha 258 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 259 the patches the way they would look like if your latest patch series was to be
259 merged. 260 merged.
260 261
261 In cases where full revert is needed the rever 262 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 263 as a patch to the list with a commit message explaining the technical
263 problems with the reverted commit. Reverts sho 264 problems with the reverted commit. Reverts should be used as a last resort,
264 when original change is completely wrong; incr 265 when original change is completely wrong; incremental fixes are preferred.
265 266
266 Stable tree 267 Stable tree
267 ~~~~~~~~~~~ 268 ~~~~~~~~~~~
268 269
269 While it used to be the case that netdev submi 270 While it used to be the case that netdev submissions were not supposed
270 to carry explicit ``CC: stable@vger.kernel.org 271 to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
271 the case today. Please follow the standard sta 272 the case today. Please follow the standard stable rules in
272 :ref:`Documentation/process/stable-kernel-rule 273 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
273 and make sure you include appropriate Fixes ta 274 and make sure you include appropriate Fixes tags!
274 275
275 Security fixes 276 Security fixes
276 ~~~~~~~~~~~~~~ 277 ~~~~~~~~~~~~~~
277 278
278 Do not email netdev maintainers directly if yo 279 Do not email netdev maintainers directly if you think you discovered
279 a bug that might have possible security implic 280 a bug that might have possible security implications.
280 The current netdev maintainer has consistently 281 The current netdev maintainer has consistently requested that
281 people use the mailing lists and not reach out 282 people use the mailing lists and not reach out directly. If you aren't
282 OK with that, then perhaps consider mailing se 283 OK with that, then perhaps consider mailing security@kernel.org or
283 reading about http://oss-security.openwall.org 284 reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
284 as possible alternative mechanisms. 285 as possible alternative mechanisms.
285 286
286 287
287 Co-posting changes to user space components 288 Co-posting changes to user space components
288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
289 290
290 User space code exercising kernel features sho 291 User space code exercising kernel features should be posted
291 alongside kernel patches. This gives reviewers 292 alongside kernel patches. This gives reviewers a chance to see
292 how any new interface is used and how well it 293 how any new interface is used and how well it works.
293 294
294 When user space tools reside in the kernel rep 295 When user space tools reside in the kernel repo itself all changes
295 should generally come as one series. If series 296 should generally come as one series. If series becomes too large
296 or the user space project is not reviewed on n 297 or the user space project is not reviewed on netdev include a link
297 to a public repo where user space patches can 298 to a public repo where user space patches can be seen.
298 299
299 In case user space tooling lives in a separate 300 In case user space tooling lives in a separate repository but is
300 reviewed on netdev (e.g. patches to ``iproute 301 reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and
301 user space patches should form separate series 302 user space patches should form separate series (threads) when posted
302 to the mailing list, e.g.:: 303 to the mailing list, e.g.::
303 304
304 [PATCH net-next 0/3] net: some feature cover 305 [PATCH net-next 0/3] net: some feature cover letter
305 └─ [PATCH net-next 1/3] net: some featu 306 └─ [PATCH net-next 1/3] net: some feature prep
306 └─ [PATCH net-next 2/3] net: some featu 307 └─ [PATCH net-next 2/3] net: some feature do it
307 └─ [PATCH net-next 3/3] selftest: net: 308 └─ [PATCH net-next 3/3] selftest: net: some feature
308 309
309 [PATCH iproute2-next] ip: add support for so 310 [PATCH iproute2-next] ip: add support for some feature
310 311
311 Posting as one thread is discouraged because i 312 Posting as one thread is discouraged because it confuses patchwork
312 (as of patchwork 2.2.2). 313 (as of patchwork 2.2.2).
313 314
314 Preparing changes 315 Preparing changes
315 ----------------- 316 -----------------
316 317
317 Attention to detail is important. Re-read you 318 Attention to detail is important. Re-read your own work as if you were the
318 reviewer. You can start with using ``checkpat 319 reviewer. You can start with using ``checkpatch.pl``, perhaps even with
319 the ``--strict`` flag. But do not be mindless 320 the ``--strict`` flag. But do not be mindlessly robotic in doing so.
320 If your change is a bug fix, make sure your co 321 If your change is a bug fix, make sure your commit log indicates the
321 end-user visible symptom, the underlying reaso 322 end-user visible symptom, the underlying reason as to why it happens,
322 and then if necessary, explain why the fix pro 323 and then if necessary, explain why the fix proposed is the best way to
323 get things done. Don't mangle whitespace, and 324 get things done. Don't mangle whitespace, and as is common, don't
324 mis-indent function arguments that span multip 325 mis-indent function arguments that span multiple lines. If it is your
325 first patch, mail it to yourself so you can te 326 first patch, mail it to yourself so you can test apply it to an
326 unpatched tree to confirm infrastructure didn' 327 unpatched tree to confirm infrastructure didn't mangle it.
327 328
328 Finally, go back and read 329 Finally, go back and read
329 :ref:`Documentation/process/submitting-patches 330 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
330 to be sure you are not repeating some common m 331 to be sure you are not repeating some common mistake documented there.
331 332
332 Indicating target tree 333 Indicating target tree
333 ~~~~~~~~~~~~~~~~~~~~~~ 334 ~~~~~~~~~~~~~~~~~~~~~~
334 335
335 To help maintainers and CI bots you should exp 336 To help maintainers and CI bots you should explicitly mark which tree
336 your patch is targeting. Assuming that you use 337 your patch is targeting. Assuming that you use git, use the prefix
337 flag:: 338 flag::
338 339
339 git format-patch --subject-prefix='PATCH net 340 git format-patch --subject-prefix='PATCH net-next' start..finish
340 341
341 Use ``net`` instead of ``net-next`` (always lo 342 Use ``net`` instead of ``net-next`` (always lower case) in the above for
342 bug-fix ``net`` content. 343 bug-fix ``net`` content.
343 344
344 Dividing work into patches 345 Dividing work into patches
345 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 346 ~~~~~~~~~~~~~~~~~~~~~~~~~~
346 347
347 Put yourself in the shoes of the reviewer. Eac 348 Put yourself in the shoes of the reviewer. Each patch is read separately
348 and therefore should constitute a comprehensib 349 and therefore should constitute a comprehensible step towards your stated
349 goal. 350 goal.
350 351
351 Avoid sending series longer than 15 patches. L 352 Avoid sending series longer than 15 patches. Larger series takes longer
352 to review as reviewers will defer looking at i 353 to review as reviewers will defer looking at it until they find a large
353 chunk of time. A small series can be reviewed 354 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 355 just do it. As a result, a sequence of smaller series gets merged quicker and
355 with better review coverage. Re-posting large 356 with better review coverage. Re-posting large series also increases the mailing
356 list traffic. 357 list traffic.
357 358
>> 359 Multi-line comments
>> 360 ~~~~~~~~~~~~~~~~~~~
>> 361
>> 362 Comment style convention is slightly different for networking and most of
>> 363 the tree. Instead of this::
>> 364
>> 365 /*
>> 366 * foobar blah blah blah
>> 367 * another line of text
>> 368 */
>> 369
>> 370 it is requested that you make it look like this::
>> 371
>> 372 /* foobar blah blah blah
>> 373 * another line of text
>> 374 */
>> 375
358 Local variable ordering ("reverse xmas tree", 376 Local variable ordering ("reverse xmas tree", "RCS")
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 377 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
360 378
361 Netdev has a convention for ordering local var 379 Netdev has a convention for ordering local variables in functions.
362 Order the variable declaration lines longest t 380 Order the variable declaration lines longest to shortest, e.g.::
363 381
364 struct scatterlist *sg; 382 struct scatterlist *sg;
365 struct sk_buff *skb; 383 struct sk_buff *skb;
366 int err, i; 384 int err, i;
367 385
368 If there are dependencies between the variable 386 If there are dependencies between the variables preventing the ordering
369 move the initialization out of line. 387 move the initialization out of line.
370 388
371 Format precedence 389 Format precedence
372 ~~~~~~~~~~~~~~~~~ 390 ~~~~~~~~~~~~~~~~~
373 391
374 When working in existing code which uses nonst 392 When working in existing code which uses nonstandard formatting make
375 your code follow the most recent guidelines, s 393 your code follow the most recent guidelines, so that eventually all code
376 in the domain of netdev is in the preferred fo 394 in the domain of netdev is in the preferred format.
377 <<
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 395
394 Resending after review 396 Resending after review
395 ~~~~~~~~~~~~~~~~~~~~~~ 397 ~~~~~~~~~~~~~~~~~~~~~~
396 398
397 Allow at least 24 hours to pass between postin 399 Allow at least 24 hours to pass between postings. This will ensure reviewers
398 from all geographical locations have a chance 400 from all geographical locations have a chance to chime in. Do not wait
399 too long (weeks) between postings either as it 401 too long (weeks) between postings either as it will make it harder for reviewers
400 to recall all the context. 402 to recall all the context.
401 403
402 Make sure you address all the feedback in your 404 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 405 version of the code if the discussion about the previous version is still
404 ongoing, unless directly instructed by a revie 406 ongoing, unless directly instructed by a reviewer.
405 407
406 The new version of patches should be posted as 408 The new version of patches should be posted as a separate thread,
407 not as a reply to the previous posting. Change 409 not as a reply to the previous posting. Change log should include a link
408 to the previous posting (see :ref:`Changes req 410 to the previous posting (see :ref:`Changes requested`).
409 411
410 Testing 412 Testing
411 ------- 413 -------
412 414
413 Expected level of testing 415 Expected level of testing
414 ~~~~~~~~~~~~~~~~~~~~~~~~~ 416 ~~~~~~~~~~~~~~~~~~~~~~~~~
415 417
416 At the very minimum your changes must survive 418 At the very minimum your changes must survive an ``allyesconfig`` and an
417 ``allmodconfig`` build with ``W=1`` set withou 419 ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
418 420
419 Ideally you will have done run-time testing sp 421 Ideally you will have done run-time testing specific to your change,
420 and the patch series contains a set of kernel 422 and the patch series contains a set of kernel selftest for
421 ``tools/testing/selftests/net`` or using the K 423 ``tools/testing/selftests/net`` or using the KUnit framework.
422 424
423 You are expected to test your changes on top o 425 You are expected to test your changes on top of the relevant networking
424 tree (``net`` or ``net-next``) and not e.g. a 426 tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
425 427
426 patchwork checks 428 patchwork checks
427 ~~~~~~~~~~~~~~~~ 429 ~~~~~~~~~~~~~~~~
428 430
429 Checks in patchwork are mostly simple wrappers 431 Checks in patchwork are mostly simple wrappers around existing kernel
430 scripts, the sources are available at: 432 scripts, the sources are available at:
431 433
432 https://github.com/linux-netdev/nipa/tree/mast 434 https://github.com/linux-netdev/nipa/tree/master/tests
433 435
434 **Do not** post your patches just to run them 436 **Do not** post your patches just to run them through the checks.
435 You must ensure that your patches are ready by 437 You must ensure that your patches are ready by testing them locally
436 before posting to the mailing list. The patchw 438 before posting to the mailing list. The patchwork build bot instance
437 gets overloaded very easily and netdev@vger re 439 gets overloaded very easily and netdev@vger really doesn't need more
438 traffic if we can help it. 440 traffic if we can help it.
439 441
440 netdevsim 442 netdevsim
441 ~~~~~~~~~ 443 ~~~~~~~~~
442 444
443 ``netdevsim`` is a test driver which can be us 445 ``netdevsim`` is a test driver which can be used to exercise driver
444 configuration APIs without requiring capable h 446 configuration APIs without requiring capable hardware.
445 Mock-ups and tests based on ``netdevsim`` are 447 Mock-ups and tests based on ``netdevsim`` are strongly encouraged when
446 adding new APIs, but ``netdevsim`` in itself i 448 adding new APIs, but ``netdevsim`` in itself is **not** considered
447 a use case/user. You must also implement the n 449 a use case/user. You must also implement the new APIs in a real driver.
448 450
449 We give no guarantees that ``netdevsim`` won't 451 We give no guarantees that ``netdevsim`` won't change in the future
450 in a way which would break what would normally 452 in a way which would break what would normally be considered uAPI.
451 453
452 ``netdevsim`` is reserved for use by upstream 454 ``netdevsim`` is reserved for use by upstream tests only, so any
453 new ``netdevsim`` features must be accompanied 455 new ``netdevsim`` features must be accompanied by selftests under
454 ``tools/testing/selftests/``. 456 ``tools/testing/selftests/``.
455 457
456 Reviewer guidance 458 Reviewer guidance
457 ----------------- 459 -----------------
458 460
459 Reviewing other people's patches on the list i 461 Reviewing other people's patches on the list is highly encouraged,
460 regardless of the level of expertise. For gene 462 regardless of the level of expertise. For general guidance and
461 helpful tips please see :ref:`development_adva 463 helpful tips please see :ref:`development_advancedtopics_reviews`.
462 464
463 It's safe to assume that netdev maintainers kn 465 It's safe to assume that netdev maintainers know the community and the level
464 of expertise of the reviewers. The reviewers s 466 of expertise of the reviewers. The reviewers should not be concerned about
465 their comments impeding or derailing the patch 467 their comments impeding or derailing the patch flow.
466 468
467 Less experienced reviewers are highly encourag 469 Less experienced reviewers are highly encouraged to do more in-depth
468 review of submissions and not focus exclusivel 470 review of submissions and not focus exclusively on trivial or subjective
469 matters like code formatting, tags etc. 471 matters like code formatting, tags etc.
470 472
471 Testimonials / feedback 473 Testimonials / feedback
472 ----------------------- 474 -----------------------
473 475
474 Some companies use peer feedback in employee p 476 Some companies use peer feedback in employee performance reviews.
475 Please feel free to request feedback from netd 477 Please feel free to request feedback from netdev maintainers,
476 especially if you spend significant amount of 478 especially if you spend significant amount of time reviewing code
477 and go out of your way to improve shared infra 479 and go out of your way to improve shared infrastructure.
478 480
479 The feedback must be requested by you, the con 481 The feedback must be requested by you, the contributor, and will always
480 be shared with you (even if you request for it 482 be shared with you (even if you request for it to be submitted to your
481 manager). 483 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.