1 .. SPDX-License-Identifier: GPL-2.0 2 3 .. _netdev-FAQ: 4 5 ============================= 6 Networking subsystem (netdev) 7 ============================= 8 9 tl;dr 10 ----- 11 12 - designate your patch to a tree - ``[PATCH n 13 - for fixes the ``Fixes:`` tag is required, r 14 - don't post large series (> 15 patches), bre 15 - don't repost your patches within one 24h pe 16 - reverse xmas tree 17 18 netdev 19 ------ 20 21 netdev is a mailing list for all network-relat 22 includes anything found under net/ (i.e. core 23 drivers/net (i.e. hardware specific drivers) i 24 25 Note that some subsystems (e.g. wireless drive 26 volume of traffic have their own specific mail 27 28 Like many other Linux mailing lists, the netde 29 kernel.org with archives available at https:// 30 31 Aside from subsystems like those mentioned abo 32 Linux development (i.e. RFC, review, comments, 33 netdev. 34 35 Development cycle 36 ----------------- 37 38 Here is a bit of background information on 39 the cadence of Linux development. Each new re 40 two week "merge window" where the main maintai 41 to Linus for merging into the mainline tree. 42 merge window is closed, and it is called/tagge 43 features get mainlined after this -- only fixe 44 expected. After roughly a week of collecting 45 rc2 is released. This repeats on a roughly we 46 (typically; sometimes rc6 if things are quiet, 47 state of churn), and a week after the last vX. 48 official vX.Y is released. 49 50 To find out where we are now in the cycle - lo 51 page here: 52 53 https://git.kernel.org/pub/scm/linux/kernel/ 54 55 and note the top of the "tags" section. If it 56 the dev cycle. If it was tagged rc7 a week ag 57 probably imminent. If the most recent tag is a 58 (without an ``-rcN`` suffix) - we are most lik 59 and ``net-next`` is closed. 60 61 git trees and patch flow 62 ------------------------ 63 64 There are two networking trees (git repositori 65 driven by David Miller, the main network maint 66 ``net`` tree, and the ``net-next`` tree. As y 67 the names, the ``net`` tree is for fixes to ex 68 mainline tree from Linus, and ``net-next`` is 69 for the future release. You can find the tree 70 71 - https://git.kernel.org/pub/scm/linux/kernel/ 72 - https://git.kernel.org/pub/scm/linux/kernel/ 73 74 Relating that to kernel development: At the be 75 merge window, the ``net-next`` tree will be cl 76 The accumulated new content of the past ~10 we 77 mainline/Linus via a pull request for vX.Y -- 78 ``net`` tree will start accumulating fixes for 79 relating to vX.Y 80 81 An announcement indicating when ``net-next`` h 82 sent to netdev, but knowing the above, you can 83 84 .. warning:: 85 Do not send new ``net-next`` content to netd 86 period during which ``net-next`` tree is clo 87 88 RFC patches sent for review only are obviously 89 (use ``--subject-prefix='RFC net-next'`` with 90 91 Shortly after the two weeks have passed (and v 92 tree for ``net-next`` reopens to collect conte 93 release. 94 95 If you aren't subscribed to netdev and/or are 96 ``net-next`` has re-opened yet, simply check t 97 repository link above for any new networking-r 98 also check the following website for the curre 99 100 https://netdev.bots.linux.dev/net-next.html 101 102 The ``net`` tree continues to collect fixes fo 103 fed back to Linus at regular (~weekly) interva 104 focus for ``net`` is on stabilization and bug 105 106 Finally, the vX.Y gets released, and the whole 107 108 netdev patch review 109 ------------------- 110 111 .. _patch_status: 112 113 Patch status 114 ~~~~~~~~~~~~ 115 116 Status of a patch can be checked by looking at 117 queue for netdev: 118 119 https://patchwork.kernel.org/project/netdevb 120 121 The "State" field will tell you exactly where 122 patch: 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 154 the value of ``Message-ID`` to the URL above. 155 156 Updating patch status 157 ~~~~~~~~~~~~~~~~~~~~~ 158 159 Contributors and reviewers do not have the per 160 state directly in patchwork. Patchwork doesn't 161 about the history of the state of patches, the 162 people update the state leads to confusion. 163 164 Instead of delegating patchwork permissions ne 165 bot which looks for special commands/lines wit 166 the mailing list. For example to mark a series 167 one needs to send the following line anywhere 168 169 pw-bot: changes-requested 170 171 As a result the bot will set the entire series 172 This may be useful when author discovers a bug 173 and wants to prevent it from getting applied. 174 175 The use of the bot is entirely optional, if in 176 completely. Maintainers will classify and upda 177 themselves. No email should ever be sent to th 178 of communicating with the bot, the bot command 179 180 The use of the bot is restricted to authors of 181 header on patch submission and command must ma 182 the modified code according to the MAINTAINERS 183 must match the MAINTAINERS entry) and a handfu 184 185 Bot records its activity here: 186 187 https://netdev.bots.linux.dev/pw-bot.html 188 189 Review timelines 190 ~~~~~~~~~~~~~~~~ 191 192 Generally speaking, the patches get triaged qu 193 48h). But be patient, if your patch is active 194 listed on the project's patch list) the chance 195 196 The high volume of development on netdev makes 197 from discussions relatively quickly. New comme 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 215 Changes requested 216 ~~~~~~~~~~~~~~~~~ 217 218 Patches :ref:`marked<patch_status>` as ``Chang 219 to be revised. The new version should come wit 220 preferably including links to previous posting 221 222 [PATCH net-next v3] net: make cows go moo 223 224 Even users who don't drink milk appreciate h 225 226 The amount of mooing will depend on packet r 227 the diurnal cycle quite well. 228 229 Signed-off-by: Joe Defarmer <joe@barn.org> 230 --- 231 v3: 232 - add a note about time-of-day mooing fluc 233 v2: https://lore.kernel.org/netdev/123themes 234 - fix missing argument in kernel doc for n 235 - fix memory leak in netdev_register_cow() 236 v1: https://lore.kernel.org/netdev/456getsth 237 238 The commit message should be revised to answer 239 had to ask in previous discussions. Occasional 240 the commit message will be the only change in 241 242 Partial resends 243 ~~~~~~~~~~~~~~~ 244 245 Please always resend the entire patch series a 246 patches such that it is clear this is the late 247 that can be applied. Do not try to resend just 248 249 Handling misapplied patches 250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 251 252 Occasionally a patch series gets applied befor 253 or the wrong version of a series gets applied. 254 255 Making the patch disappear once it is pushed o 256 history in netdev trees is immutable. 257 Please send incremental versions on top of wha 258 the patches the way they would look like if yo 259 merged. 260 261 In cases where full revert is needed the rever 262 as a patch to the list with a commit message e 263 problems with the reverted commit. Reverts sho 264 when original change is completely wrong; incr 265 266 Stable tree 267 ~~~~~~~~~~~ 268 269 While it used to be the case that netdev submi 270 to carry explicit ``CC: stable@vger.kernel.org 271 the case today. Please follow the standard sta 272 :ref:`Documentation/process/stable-kernel-rule 273 and make sure you include appropriate Fixes ta 274 275 Security fixes 276 ~~~~~~~~~~~~~~ 277 278 Do not email netdev maintainers directly if yo 279 a bug that might have possible security implic 280 The current netdev maintainer has consistently 281 people use the mailing lists and not reach out 282 OK with that, then perhaps consider mailing se 283 reading about http://oss-security.openwall.org 284 as possible alternative mechanisms. 285 286 287 Co-posting changes to user space components 288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 289 290 User space code exercising kernel features sho 291 alongside kernel patches. This gives reviewers 292 how any new interface is used and how well it 293 294 When user space tools reside in the kernel rep 295 should generally come as one series. If series 296 or the user space project is not reviewed on n 297 to a public repo where user space patches can 298 299 In case user space tooling lives in a separate 300 reviewed on netdev (e.g. patches to ``iproute 301 user space patches should form separate series 302 to the mailing list, e.g.:: 303 304 [PATCH net-next 0/3] net: some feature cover 305 └─ [PATCH net-next 1/3] net: some featu 306 └─ [PATCH net-next 2/3] net: some featu 307 └─ [PATCH net-next 3/3] selftest: net: 308 309 [PATCH iproute2-next] ip: add support for so 310 311 Posting as one thread is discouraged because i 312 (as of patchwork 2.2.2). 313 314 Preparing changes 315 ----------------- 316 317 Attention to detail is important. Re-read you 318 reviewer. You can start with using ``checkpat 319 the ``--strict`` flag. But do not be mindless 320 If your change is a bug fix, make sure your co 321 end-user visible symptom, the underlying reaso 322 and then if necessary, explain why the fix pro 323 get things done. Don't mangle whitespace, and 324 mis-indent function arguments that span multip 325 first patch, mail it to yourself so you can te 326 unpatched tree to confirm infrastructure didn' 327 328 Finally, go back and read 329 :ref:`Documentation/process/submitting-patches 330 to be sure you are not repeating some common m 331 332 Indicating target tree 333 ~~~~~~~~~~~~~~~~~~~~~~ 334 335 To help maintainers and CI bots you should exp 336 your patch is targeting. Assuming that you use 337 flag:: 338 339 git format-patch --subject-prefix='PATCH net 340 341 Use ``net`` instead of ``net-next`` (always lo 342 bug-fix ``net`` content. 343 344 Dividing work into patches 345 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 346 347 Put yourself in the shoes of the reviewer. Eac 348 and therefore should constitute a comprehensib 349 goal. 350 351 Avoid sending series longer than 15 patches. L 352 to review as reviewers will defer looking at i 353 chunk of time. A small series can be reviewed 354 just do it. As a result, a sequence of smaller 355 with better review coverage. Re-posting large 356 list traffic. 357 358 Local variable ordering ("reverse xmas tree", 359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 360 361 Netdev has a convention for ordering local var 362 Order the variable declaration lines longest t 363 364 struct scatterlist *sg; 365 struct sk_buff *skb; 366 int err, i; 367 368 If there are dependencies between the variable 369 move the initialization out of line. 370 371 Format precedence 372 ~~~~~~~~~~~~~~~~~ 373 374 When working in existing code which uses nonst 375 your code follow the most recent guidelines, s 376 in the domain of netdev is in the preferred fo 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 394 Resending after review 395 ~~~~~~~~~~~~~~~~~~~~~~ 396 397 Allow at least 24 hours to pass between postin 398 from all geographical locations have a chance 399 too long (weeks) between postings either as it 400 to recall all the context. 401 402 Make sure you address all the feedback in your 403 version of the code if the discussion about th 404 ongoing, unless directly instructed by a revie 405 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 411 ------- 412 413 Expected level of testing 414 ~~~~~~~~~~~~~~~~~~~~~~~~~ 415 416 At the very minimum your changes must survive 417 ``allmodconfig`` build with ``W=1`` set withou 418 419 Ideally you will have done run-time testing sp 420 and the patch series contains a set of kernel 421 ``tools/testing/selftests/net`` or using the K 422 423 You are expected to test your changes on top o 424 tree (``net`` or ``net-next``) and not e.g. a 425 426 patchwork checks 427 ~~~~~~~~~~~~~~~~ 428 429 Checks in patchwork are mostly simple wrappers 430 scripts, the sources are available at: 431 432 https://github.com/linux-netdev/nipa/tree/mast 433 434 **Do not** post your patches just to run them 435 You must ensure that your patches are ready by 436 before posting to the mailing list. The patchw 437 gets overloaded very easily and netdev@vger re 438 traffic if we can help it. 439 440 netdevsim 441 ~~~~~~~~~ 442 443 ``netdevsim`` is a test driver which can be us 444 configuration APIs without requiring capable h 445 Mock-ups and tests based on ``netdevsim`` are 446 adding new APIs, but ``netdevsim`` in itself i 447 a use case/user. You must also implement the n 448 449 We give no guarantees that ``netdevsim`` won't 450 in a way which would break what would normally 451 452 ``netdevsim`` is reserved for use by upstream 453 new ``netdevsim`` features must be accompanied 454 ``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 471 Testimonials / feedback 472 ----------------------- 473 474 Some companies use peer feedback in employee p 475 Please feel free to request feedback from netd 476 especially if you spend significant amount of 477 and go out of your way to improve shared infra 478 479 The feedback must be requested by you, the con 480 be shared with you (even if you request for it 481 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.