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 http://vger.kernel.org/~davem/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. Patches are indexed by the ``Message-ID`` header of the emails 124which carried them so if you have trouble finding your patch append 125the value of ``Message-ID`` to the URL above. 126 127Updating patch status 128~~~~~~~~~~~~~~~~~~~~~ 129 130It may be tempting to help the maintainers and update the state of your 131own patches when you post a new version or spot a bug. Please **do not** 132do that. 133Interfering with the patch status on patchwork will only cause confusion. Leave 134it to the maintainer to figure out what is the most recent and current 135version that should be applied. If there is any doubt, the maintainer 136will reply and ask what should be done. 137 138Review timelines 139~~~~~~~~~~~~~~~~ 140 141Generally speaking, the patches get triaged quickly (in less than 14248h). But be patient, if your patch is active in patchwork (i.e. it's 143listed on the project's patch list) the chances it was missed are close to zero. 144Asking the maintainer for status updates on your 145patch is a good way to ensure your patch is ignored or pushed to the 146bottom of the priority list. 147 148Changes requested 149~~~~~~~~~~~~~~~~~ 150 151Patches :ref:`marked<patch_status>` as ``Changes Requested`` need 152to be revised. The new version should come with a change log, 153preferably including links to previous postings, for example:: 154 155 [PATCH net-next v3] net: make cows go moo 156 157 Even users who don't drink milk appreciate hearing the cows go "moo". 158 159 The amount of mooing will depend on packet rate so should match 160 the diurnal cycle quite well. 161 162 Signed-of-by: Joe Defarmer <joe@barn.org> 163 --- 164 v3: 165 - add a note about time-of-day mooing fluctuation to the commit message 166 v2: https://lore.kernel.org/netdev/123themessageid@barn.org/ 167 - fix missing argument in kernel doc for netif_is_bovine() 168 - fix memory leak in netdev_register_cow() 169 v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/ 170 171The commit message should be revised to answer any questions reviewers 172had to ask in previous discussions. Occasionally the update of 173the commit message will be the only change in the new version. 174 175Partial resends 176~~~~~~~~~~~~~~~ 177 178Please always resend the entire patch series and make sure you do number your 179patches such that it is clear this is the latest and greatest set of patches 180that can be applied. Do not try to resend just the patches which changed. 181 182Handling misapplied patches 183~~~~~~~~~~~~~~~~~~~~~~~~~~~ 184 185Occasionally a patch series gets applied before receiving critical feedback, 186or the wrong version of a series gets applied. 187 188Making the patch disappear once it is pushed out is not possible, the commit 189history in netdev trees is immutable. 190Please send incremental versions on top of what has been merged in order to fix 191the patches the way they would look like if your latest patch series was to be 192merged. 193 194In cases where full revert is needed the revert has to be submitted 195as a patch to the list with a commit message explaining the technical 196problems with the reverted commit. Reverts should be used as a last resort, 197when original change is completely wrong; incremental fixes are preferred. 198 199Stable tree 200~~~~~~~~~~~ 201 202While it used to be the case that netdev submissions were not supposed 203to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer 204the case today. Please follow the standard stable rules in 205:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`, 206and make sure you include appropriate Fixes tags! 207 208Security fixes 209~~~~~~~~~~~~~~ 210 211Do not email netdev maintainers directly if you think you discovered 212a bug that might have possible security implications. 213The current netdev maintainer has consistently requested that 214people use the mailing lists and not reach out directly. If you aren't 215OK with that, then perhaps consider mailing security@kernel.org or 216reading about http://oss-security.openwall.org/wiki/mailing-lists/distros 217as possible alternative mechanisms. 218 219 220Co-posting changes to user space components 221~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 222 223User space code exercising kernel features should be posted 224alongside kernel patches. This gives reviewers a chance to see 225how any new interface is used and how well it works. 226 227When user space tools reside in the kernel repo itself all changes 228should generally come as one series. If series becomes too large 229or the user space project is not reviewed on netdev include a link 230to a public repo where user space patches can be seen. 231 232In case user space tooling lives in a separate repository but is 233reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and 234user space patches should form separate series (threads) when posted 235to the mailing list, e.g.:: 236 237 [PATCH net-next 0/3] net: some feature cover letter 238 └─ [PATCH net-next 1/3] net: some feature prep 239 └─ [PATCH net-next 2/3] net: some feature do it 240 └─ [PATCH net-next 3/3] selftest: net: some feature 241 242 [PATCH iproute2-next] ip: add support for some feature 243 244Posting as one thread is discouraged because it confuses patchwork 245(as of patchwork 2.2.2). 246 247Preparing changes 248----------------- 249 250Attention to detail is important. Re-read your own work as if you were the 251reviewer. You can start with using ``checkpatch.pl``, perhaps even with 252the ``--strict`` flag. But do not be mindlessly robotic in doing so. 253If your change is a bug fix, make sure your commit log indicates the 254end-user visible symptom, the underlying reason as to why it happens, 255and then if necessary, explain why the fix proposed is the best way to 256get things done. Don't mangle whitespace, and as is common, don't 257mis-indent function arguments that span multiple lines. If it is your 258first patch, mail it to yourself so you can test apply it to an 259unpatched tree to confirm infrastructure didn't mangle it. 260 261Finally, go back and read 262:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` 263to be sure you are not repeating some common mistake documented there. 264 265Indicating target tree 266~~~~~~~~~~~~~~~~~~~~~~ 267 268To help maintainers and CI bots you should explicitly mark which tree 269your patch is targeting. Assuming that you use git, use the prefix 270flag:: 271 272 git format-patch --subject-prefix='PATCH net-next' start..finish 273 274Use ``net`` instead of ``net-next`` (always lower case) in the above for 275bug-fix ``net`` content. 276 277Dividing work into patches 278~~~~~~~~~~~~~~~~~~~~~~~~~~ 279 280Put yourself in the shoes of the reviewer. Each patch is read separately 281and therefore should constitute a comprehensible step towards your stated 282goal. 283 284Avoid sending series longer than 15 patches. Larger series takes longer 285to review as reviewers will defer looking at it until they find a large 286chunk of time. A small series can be reviewed in a short time, so Maintainers 287just do it. As a result, a sequence of smaller series gets merged quicker and 288with better review coverage. Re-posting large series also increases the mailing 289list traffic. 290 291Multi-line comments 292~~~~~~~~~~~~~~~~~~~ 293 294Comment style convention is slightly different for networking and most of 295the tree. Instead of this:: 296 297 /* 298 * foobar blah blah blah 299 * another line of text 300 */ 301 302it is requested that you make it look like this:: 303 304 /* foobar blah blah blah 305 * another line of text 306 */ 307 308Local variable ordering ("reverse xmas tree", "RCS") 309~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 310 311Netdev has a convention for ordering local variables in functions. 312Order the variable declaration lines longest to shortest, e.g.:: 313 314 struct scatterlist *sg; 315 struct sk_buff *skb; 316 int err, i; 317 318If there are dependencies between the variables preventing the ordering 319move the initialization out of line. 320 321Format precedence 322~~~~~~~~~~~~~~~~~ 323 324When working in existing code which uses nonstandard formatting make 325your code follow the most recent guidelines, so that eventually all code 326in the domain of netdev is in the preferred format. 327 328Resending after review 329~~~~~~~~~~~~~~~~~~~~~~ 330 331Allow at least 24 hours to pass between postings. This will ensure reviewers 332from all geographical locations have a chance to chime in. Do not wait 333too long (weeks) between postings either as it will make it harder for reviewers 334to recall all the context. 335 336Make sure you address all the feedback in your new posting. Do not post a new 337version of the code if the discussion about the previous version is still 338ongoing, unless directly instructed by a reviewer. 339 340Testing 341------- 342 343Expected level of testing 344~~~~~~~~~~~~~~~~~~~~~~~~~ 345 346At the very minimum your changes must survive an ``allyesconfig`` and an 347``allmodconfig`` build with ``W=1`` set without new warnings or failures. 348 349Ideally you will have done run-time testing specific to your change, 350and the patch series contains a set of kernel selftest for 351``tools/testing/selftests/net`` or using the KUnit framework. 352 353You are expected to test your changes on top of the relevant networking 354tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``. 355 356patchwork checks 357~~~~~~~~~~~~~~~~ 358 359Checks in patchwork are mostly simple wrappers around existing kernel 360scripts, the sources are available at: 361 362https://github.com/kuba-moo/nipa/tree/master/tests 363 364**Do not** post your patches just to run them through the checks. 365You must ensure that your patches are ready by testing them locally 366before posting to the mailing list. The patchwork build bot instance 367gets overloaded very easily and netdev@vger really doesn't need more 368traffic if we can help it. 369 370netdevsim 371~~~~~~~~~ 372 373``netdevsim`` is a test driver which can be used to exercise driver 374configuration APIs without requiring capable hardware. 375Mock-ups and tests based on ``netdevsim`` are strongly encouraged when 376adding new APIs, but ``netdevsim`` in itself is **not** considered 377a use case/user. You must also implement the new APIs in a real driver. 378 379We give no guarantees that ``netdevsim`` won't change in the future 380in a way which would break what would normally be considered uAPI. 381 382``netdevsim`` is reserved for use by upstream tests only, so any 383new ``netdevsim`` features must be accompanied by selftests under 384``tools/testing/selftests/``. 385 386Testimonials / feedback 387----------------------- 388 389Some companies use peer feedback in employee performance reviews. 390Please feel free to request feedback from netdev maintainers, 391especially if you spend significant amount of time reviewing code 392and go out of your way to improve shared infrastructure. 393 394The feedback must be requested by you, the contributor, and will always 395be shared with you (even if you request for it to be submitted to your 396manager). 397