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