| 1 | |
| 2 |
|
| 3 | |
| 4 |
|
| 5 | =============================
|
| 6 | Networking subsystem (netdev)
|
| 7 | =============================
|
| 8 |
|
| 9 | tl;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 |
|
| 18 | netdev
|
| 19 | ------
|
| 20 |
|
| 21 | netdev is a mailing list for all network-related Linux stuff. This
|
| 22 | includes anything found under net/ (i.e. core code like IPv6) and
|
| 23 | drivers/net (i.e. hardware specific drivers) in the Linux source tree.
|
| 24 |
|
| 25 | Note that some subsystems (e.g. wireless drivers) which have a high
|
| 26 | volume of traffic have their own specific mailing lists and trees.
|
| 27 |
|
| 28 | Like many other Linux mailing lists, the netdev list is hosted at
|
| 29 | kernel.org with archives available at https://lore.kernel.org/netdev/.
|
| 30 |
|
| 31 | Aside from subsystems like those mentioned above, all network-related
|
| 32 | Linux development (i.e. RFC, review, comments, etc.) takes place on
|
| 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 release starts off with a
|
| 40 | two week "merge window" where the main maintainers feed their new stuff
|
| 41 | to Linus for merging into the mainline tree. After the two weeks, the
|
| 42 | merge window is closed, and it is called/tagged ``-rc1``. No new
|
| 43 | features get mainlined after this -- only fixes to the rc1 content are
|
| 44 | expected. After roughly a week of collecting fixes to the rc1 content,
|
| 45 | rc2 is released. This repeats on a roughly weekly basis until rc7
|
| 46 | (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.Y-rcN was done, the
|
| 48 | official vX.Y is released.
|
| 49 |
|
| 50 | To find out where we are now in the cycle - load the mainline (Linus)
|
| 51 | page here:
|
| 52 |
|
| 53 | https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
|
| 54 |
|
| 55 | 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 ago, then a release is
|
| 57 | probably imminent. If the most recent tag is a final release tag
|
| 58 | (without an ``-rcN`` suffix) - we are most likely in a merge window
|
| 59 | and ``net-next`` is closed.
|
| 60 |
|
| 61 | git trees and patch flow
|
| 62 | ------------------------
|
| 63 |
|
| 64 | There are two networking trees (git repositories) in play. Both are
|
| 65 | driven by David Miller, the main network maintainer. There is the
|
| 66 | ``net`` tree, and the ``net-next`` tree. As you can probably guess from
|
| 67 | the names, the ``net`` tree is for fixes to existing code already in the
|
| 68 | mainline tree from Linus, and ``net-next`` is where the new code goes
|
| 69 | for the future release. You can find the trees here:
|
| 70 |
|
| 71 | - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git
|
| 72 | - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git
|
| 73 |
|
| 74 | Relating that to kernel development: At the beginning of the 2-week
|
| 75 | merge window, the ``net-next`` tree will be closed - no new changes/features.
|
| 76 | The accumulated new content of the past ~10 weeks will be passed onto
|
| 77 | mainline/Linus via a pull request for vX.Y -- at the same time, the
|
| 78 | ``net`` tree will start accumulating fixes for this pulled content
|
| 79 | relating to vX.Y
|
| 80 |
|
| 81 | An announcement indicating when ``net-next`` has been closed is usually
|
| 82 | sent to netdev, but knowing the above, you can predict that in advance.
|
| 83 |
|
| 84 | .. warning::
|
| 85 | Do not send new ``net-next`` content to netdev during the
|
| 86 | period during which ``net-next`` tree is closed.
|
| 87 |
|
| 88 | RFC patches sent for review only are obviously welcome at any time
|
| 89 | (use ``--subject-prefix='RFC net-next'`` with ``git format-patch``).
|
| 90 |
|
| 91 | Shortly after the two weeks have passed (and vX.Y-rc1 is released), the
|
| 92 | tree for ``net-next`` reopens to collect content for the next (vX.Y+1)
|
| 93 | release.
|
| 94 |
|
| 95 | If you aren't subscribed to netdev and/or are simply unsure if
|
| 96 | ``net-next`` has re-opened yet, simply check the ``net-next`` git
|
| 97 | repository link above for any new networking-related commits. You may
|
| 98 | also check the following website for the current status:
|
| 99 |
|
| 100 | https://netdev.bots.linux.dev/net-next.html
|
| 101 |
|
| 102 | The ``net`` tree continues to collect fixes for the vX.Y content, and is
|
| 103 | fed back to Linus at regular (~weekly) intervals. Meaning that the
|
| 104 | focus for ``net`` is on stabilization and bug fixes.
|
| 105 |
|
| 106 | Finally, the vX.Y gets released, and the whole cycle starts over.
|
| 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 the main patchwork
|
| 117 | queue for netdev:
|
| 118 |
|
| 119 | https://patchwork.kernel.org/project/netdevbpf/list/
|
| 120 |
|
| 121 | The "State" field will tell you exactly where things are at with your
|
| 122 | patch:
|
| 123 |
|
| 124 | ================== =============================================================
|
| 125 | Patch state Description
|
| 126 | ================== =============================================================
|
| 127 | New, Under review pending review, patch is in the maintainer’s queue for
|
| 128 | review; the two states are used interchangeably (depending on
|
| 129 | the exact co-maintainer handling patchwork at the time)
|
| 130 | Accepted patch was applied to the appropriate networking tree, this is
|
| 131 | usually set automatically by the pw-bot
|
| 132 | Needs ACK waiting for an ack from an area expert or testing
|
| 133 | Changes requested patch has not passed the review, new revision is expected
|
| 134 | with appropriate code and commit message changes
|
| 135 | Rejected patch has been rejected and new revision is not expected
|
| 136 | Not applicable patch is expected to be applied outside of the networking
|
| 137 | subsystem
|
| 138 | Awaiting upstream patch should be reviewed and handled by appropriate
|
| 139 | sub-maintainer, who will send it on to the networking trees;
|
| 140 | patches set to ``Awaiting upstream`` in netdev's patchwork
|
| 141 | will usually remain in this state, whether the sub-maintainer
|
| 142 | requested changes, accepted or rejected the patch
|
| 143 | Deferred patch needs to be reposted later, usually due to dependency
|
| 144 | or because it was posted for a closed tree
|
| 145 | Superseded new version of the patch was posted, usually set by the
|
| 146 | pw-bot
|
| 147 | RFC not to be applied, usually not in maintainer’s review queue,
|
| 148 | pw-bot can automatically set patches to this state based
|
| 149 | on subject tags
|
| 150 | ================== =============================================================
|
| 151 |
|
| 152 | Patches are indexed by the ``Message-ID`` header of the emails
|
| 153 | which carried them so if you have trouble finding your patch append
|
| 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 permissions to update patch
|
| 160 | state directly in patchwork. Patchwork doesn't expose much information
|
| 161 | about the history of the state of patches, therefore having multiple
|
| 162 | people update the state leads to confusion.
|
| 163 |
|
| 164 | Instead of delegating patchwork permissions netdev uses a simple mail
|
| 165 | bot which looks for special commands/lines within the emails sent to
|
| 166 | the mailing list. For example to mark a series as Changes Requested
|
| 167 | one needs to send the following line anywhere in the email thread::
|
| 168 |
|
| 169 | pw-bot: changes-requested
|
| 170 |
|
| 171 | As a result the bot will set the entire series to Changes Requested.
|
| 172 | This may be useful when author discovers a bug in their own series
|
| 173 | and wants to prevent it from getting applied.
|
| 174 |
|
| 175 | The use of the bot is entirely optional, if in doubt ignore its existence
|
| 176 | completely. Maintainers will classify and update the state of the patches
|
| 177 | themselves. No email should ever be sent to the list with the main purpose
|
| 178 | of communicating with the bot, the bot commands should be seen as metadata.
|
| 179 |
|
| 180 | The use of the bot is restricted to authors of the patches (the ``From:``
|
| 181 | header on patch submission and command must match!), maintainers of
|
| 182 | the modified code according to the MAINTAINERS file (again, ``From:``
|
| 183 | must match the MAINTAINERS entry) and a handful of senior reviewers.
|
| 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 quickly (in less than
|
| 193 | 48h). But be patient, if your patch is active in patchwork (i.e. it's
|
| 194 | listed on the project's patch list) the chances it was missed are close to zero.
|
| 195 |
|
| 196 | The high volume of development on netdev makes reviewers move on
|
| 197 | from discussions relatively quickly. New comments and replies
|
| 198 | are very unlikely to arrive after a week of silence. If a patch
|
| 199 | is no longer active in patchwork and the thread went idle for more
|
| 200 | than a week - clarify the next steps and/or post the next version.
|
| 201 |
|
| 202 | For RFC postings specifically, if nobody responded in a week - reviewers
|
| 203 | either missed the posting or have no strong opinions. If the code is ready,
|
| 204 | repost as a PATCH.
|
| 205 |
|
| 206 | There are 2 services actively providing LLM-generated review on posted patches:
|
| 207 |
|
| 208 | - https://sashiko.dev/
|
| 209 | - https://netdev-ai.bots.linux.dev/sashiko/
|
| 210 |
|
| 211 | both use the Sashiko infrastructure on top of different models. Reviews are
|
| 212 | available after 24h. Patch authors are expected to proactively look into the
|
| 213 | AI-generated reviews and handle such feedback as any other kind of review:
|
| 214 | either debate it or address it. In both cases a reply on the mailing list is
|
| 215 | expected.
|
| 216 |
|
| 217 | Authors are strongly encouraged to run LLM reviews on the posted patches in
|
| 218 | advance of the actual post. Large series triggering a significant amount of
|
| 219 | AI-generated feedback will likely get little attention from maintainers and
|
| 220 | reviewers.
|
| 221 |
|
| 222 | Emails saying just "ping" or "bump" are considered rude. If you can't figure
|
| 223 | out the status of the patch from patchwork or where the discussion has
|
| 224 | landed - describe your best guess and ask if it's correct. For example::
|
| 225 |
|
| 226 | I don't understand what the next steps are. Person X seems to be unhappy
|
| 227 | with A, should I do B and repost the patches?
|
| 228 |
|
| 229 | Don't reach out to maintainers or reviewers via private email and/or other
|
| 230 | communications channels: all the discussion must remain public, and
|
| 231 | requesting special attention is unfair towards the community, at best.
|
| 232 |
|
| 233 | .. _Changes requested:
|
| 234 |
|
| 235 | Changes requested
|
| 236 | ~~~~~~~~~~~~~~~~~
|
| 237 |
|
| 238 | Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
|
| 239 | to be revised. The new version should come with a change log,
|
| 240 | preferably including links to previous postings, for example::
|
| 241 |
|
| 242 | [PATCH net-next v3] net: make cows go moo
|
| 243 |
|
| 244 | Even users who don't drink milk appreciate hearing the cows go "moo".
|
| 245 |
|
| 246 | The amount of mooing will depend on packet rate so should match
|
| 247 | the diurnal cycle quite well.
|
| 248 |
|
| 249 | Signed-off-by: Joe Defarmer <[email protected]>
|
| 250 | ---
|
| 251 | v3:
|
| 252 | - add a note about time-of-day mooing fluctuation to the commit message
|
| 253 | v2: https://lore.kernel.org/netdev/[email protected]/
|
| 254 | - fix missing argument in kernel doc for netif_is_bovine()
|
| 255 | - fix memory leak in netdev_register_cow()
|
| 256 | v1: https://lore.kernel.org/netdev/[email protected]/
|
| 257 |
|
| 258 | The commit message should be revised to answer any questions reviewers
|
| 259 | had to ask in previous discussions. Occasionally the update of
|
| 260 | the commit message will be the only change in the new version.
|
| 261 |
|
| 262 | Partial resends
|
| 263 | ~~~~~~~~~~~~~~~
|
| 264 |
|
| 265 | Please always resend the entire patch series and make sure you do number your
|
| 266 | patches such that it is clear this is the latest and greatest set of patches
|
| 267 | that can be applied. Do not try to resend just the patches which changed.
|
| 268 |
|
| 269 | Handling misapplied patches
|
| 270 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 271 |
|
| 272 | Occasionally a patch series gets applied before receiving critical feedback,
|
| 273 | or the wrong version of a series gets applied.
|
| 274 |
|
| 275 | Making the patch disappear once it is pushed out is not possible, the commit
|
| 276 | history in netdev trees is immutable.
|
| 277 | Please send incremental versions on top of what has been merged in order to fix
|
| 278 | the patches the way they would look like if your latest patch series was to be
|
| 279 | merged.
|
| 280 |
|
| 281 | In cases where full revert is needed the revert has to be submitted
|
| 282 | as a patch to the list with a commit message explaining the technical
|
| 283 | problems with the reverted commit. Reverts should be used as a last resort,
|
| 284 | when original change is completely wrong; incremental fixes are preferred.
|
| 285 |
|
| 286 | Stable tree
|
| 287 | ~~~~~~~~~~~
|
| 288 |
|
| 289 | While it used to be the case that netdev submissions were not supposed
|
| 290 | to carry explicit ``CC: [email protected]`` tags that is no longer
|
| 291 | the case today. Please follow the standard stable rules in
|
| 292 | :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
|
| 293 | and make sure you include appropriate Fixes tags!
|
| 294 |
|
| 295 | Security fixes
|
| 296 | ~~~~~~~~~~~~~~
|
| 297 |
|
| 298 | Do not email netdev maintainers directly if you think you discovered
|
| 299 | a bug that might have possible security implications.
|
| 300 | The current netdev maintainer has consistently requested that
|
| 301 | people use the mailing lists and not reach out directly. If you aren't
|
| 302 | OK with that, then perhaps consider mailing [email protected] or
|
| 303 | reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
|
| 304 | as possible alternative mechanisms.
|
| 305 |
|
| 306 |
|
| 307 | Co-posting changes to user space components
|
| 308 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 309 |
|
| 310 | User space code exercising kernel features should be posted
|
| 311 | alongside kernel patches. This gives reviewers a chance to see
|
| 312 | how any new interface is used and how well it works.
|
| 313 |
|
| 314 | When user space tools reside in the kernel repo itself all changes
|
| 315 | should generally come as one series. If series becomes too large
|
| 316 | or the user space project is not reviewed on netdev include a link
|
| 317 | to a public repo where user space patches can be seen.
|
| 318 |
|
| 319 | In case user space tooling lives in a separate repository but is
|
| 320 | reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and
|
| 321 | user space patches should form separate series (threads) when posted
|
| 322 | to the mailing list, e.g.::
|
| 323 |
|
| 324 | [PATCH net-next 0/3] net: some feature cover letter
|
| 325 | └─ [PATCH net-next 1/3] net: some feature prep
|
| 326 | └─ [PATCH net-next 2/3] net: some feature do it
|
| 327 | └─ [PATCH net-next 3/3] selftest: net: some feature
|
| 328 |
|
| 329 | [PATCH iproute2-next] ip: add support for some feature
|
| 330 |
|
| 331 | Posting as one thread is discouraged because it confuses patchwork
|
| 332 | (as of patchwork 2.2.2).
|
| 333 |
|
| 334 | Co-posting selftests
|
| 335 | ~~~~~~~~~~~~~~~~~~~~
|
| 336 |
|
| 337 | Selftests should be part of the same series as the code changes.
|
| 338 | Specifically for fixes both code change and related test should go into
|
| 339 | the same tree (the tests may lack a Fixes tag, which is expected).
|
| 340 | Mixing code changes and test changes in a single commit is discouraged.
|
| 341 |
|
| 342 | Preparing changes
|
| 343 | -----------------
|
| 344 |
|
| 345 | Attention to detail is important. Re-read your own work as if you were the
|
| 346 | reviewer. You can start with using ``checkpatch.pl``, perhaps even with
|
| 347 | the ``--strict`` flag. But do not be mindlessly robotic in doing so.
|
| 348 | If your change is a bug fix, make sure your commit log indicates the
|
| 349 | end-user visible symptom, the underlying reason as to why it happens,
|
| 350 | and then if necessary, explain why the fix proposed is the best way to
|
| 351 | get things done. Don't mangle whitespace, and as is common, don't
|
| 352 | mis-indent function arguments that span multiple lines. If it is your
|
| 353 | first patch, mail it to yourself so you can test apply it to an
|
| 354 | unpatched tree to confirm infrastructure didn't mangle it.
|
| 355 |
|
| 356 | Finally, go back and read
|
| 357 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
|
| 358 | to be sure you are not repeating some common mistake documented there.
|
| 359 |
|
| 360 | Indicating target tree
|
| 361 | ~~~~~~~~~~~~~~~~~~~~~~
|
| 362 |
|
| 363 | To help maintainers and CI bots you should explicitly mark which tree
|
| 364 | your patch is targeting. Assuming that you use git, use the prefix
|
| 365 | flag::
|
| 366 |
|
| 367 | git format-patch --subject-prefix='PATCH net-next' start..finish
|
| 368 |
|
| 369 | Use ``net`` instead of ``net-next`` (always lower case) in the above for
|
| 370 | bug-fix ``net`` content.
|
| 371 |
|
| 372 | Dividing work into patches
|
| 373 | ~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 374 |
|
| 375 | Put yourself in the shoes of the reviewer. Each patch is read separately
|
| 376 | and therefore should constitute a comprehensible step towards your stated
|
| 377 | goal.
|
| 378 |
|
| 379 | Avoid sending series longer than 15 patches. Larger series takes longer
|
| 380 | to review as reviewers will defer looking at it until they find a large
|
| 381 | chunk of time. A small series can be reviewed in a short time, so Maintainers
|
| 382 | just do it. As a result, a sequence of smaller series gets merged quicker and
|
| 383 | with better review coverage. Re-posting large series also increases the mailing
|
| 384 | list traffic.
|
| 385 |
|
| 386 | Limit patches outstanding on mailing list
|
| 387 | -----------------------------------------
|
| 388 |
|
| 389 | Avoid having more than 15 patches, across all series, outstanding for
|
| 390 | review on the mailing list for a single tree. In other words, a maximum of
|
| 391 | 15 patches under review on net, and a maximum of 15 patches under review on
|
| 392 | net-next.
|
| 393 |
|
| 394 | This limit is intended to focus developer effort on testing patches before
|
| 395 | upstream review. Aiding the quality of upstream submissions, and easing the
|
| 396 | load on reviewers.
|
| 397 |
|
| 398 | .. _rcs:
|
| 399 |
|
| 400 | Local variable ordering ("reverse xmas tree", "RCS")
|
| 401 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 402 |
|
| 403 | Netdev has a convention for ordering local variables in functions.
|
| 404 | Order the variable declaration lines longest to shortest, e.g.::
|
| 405 |
|
| 406 | struct scatterlist *sg;
|
| 407 | struct sk_buff *skb;
|
| 408 | int err, i;
|
| 409 |
|
| 410 | If there are dependencies between the variables preventing the ordering
|
| 411 | move the initialization out of line.
|
| 412 |
|
| 413 | Format precedence
|
| 414 | ~~~~~~~~~~~~~~~~~
|
| 415 |
|
| 416 | When working in existing code which uses nonstandard formatting make
|
| 417 | your code follow the most recent guidelines, so that eventually all code
|
| 418 | in the domain of netdev is in the preferred format.
|
| 419 |
|
| 420 | Using device-managed and cleanup.h constructs
|
| 421 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 422 |
|
| 423 | Netdev remains skeptical about promises of all "auto-cleanup" APIs,
|
| 424 | including even ``devm_`` helpers, historically. They are not the preferred
|
| 425 | style of implementation, merely an acceptable one.
|
| 426 |
|
| 427 | Use of ``guard()`` is discouraged within any function longer than 20 lines,
|
| 428 | ``scoped_guard()`` is considered more readable. Using normal lock/unlock is
|
| 429 | still (weakly) preferred.
|
| 430 |
|
| 431 | Low level cleanup constructs (such as ``__free()``) can be used when building
|
| 432 | APIs and helpers, especially scoped iterators. However, direct use of
|
| 433 | ``__free()`` within networking core and drivers is discouraged.
|
| 434 | Similar guidance applies to declaring variables mid-function.
|
| 435 |
|
| 436 | Clean-up patches
|
| 437 | ~~~~~~~~~~~~~~~~
|
| 438 |
|
| 439 | Netdev discourages patches which perform simple clean-ups, which are not in
|
| 440 | the context of other work. For example:
|
| 441 |
|
| 442 | * Addressing ``checkpatch.pl``, and other trivial coding style warnings
|
| 443 | * Addressing :ref:`Local variable ordering<rcs>` issues
|
| 444 | * Conversions to device-managed APIs (``devm_`` helpers)
|
| 445 |
|
| 446 | This is because it is felt that the churn that such changes produce comes
|
| 447 | at a greater cost than the value of such clean-ups.
|
| 448 |
|
| 449 | Conversely, spelling and grammar fixes are not discouraged.
|
| 450 |
|
| 451 | Resending after review
|
| 452 | ~~~~~~~~~~~~~~~~~~~~~~
|
| 453 |
|
| 454 | Allow at least 24 hours to pass between postings. This will ensure reviewers
|
| 455 | from all geographical locations have a chance to chime in. Do not wait
|
| 456 | too long (weeks) between postings either as it will make it harder for reviewers
|
| 457 | to recall all the context.
|
| 458 |
|
| 459 | Make sure you address all the feedback in your new posting. Do not post a new
|
| 460 | version of the code if the discussion about the previous version is still
|
| 461 | ongoing, unless directly instructed by a reviewer.
|
| 462 |
|
| 463 | The new version of patches should be posted as a separate thread,
|
| 464 | not as a reply to the previous posting. Change log should include a link
|
| 465 | to the previous posting (see :ref:`Changes requested`).
|
| 466 |
|
| 467 | Testing
|
| 468 | -------
|
| 469 |
|
| 470 | Expected level of testing
|
| 471 | ~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 472 |
|
| 473 | At the very minimum your changes must survive an ``allyesconfig`` and an
|
| 474 | ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
|
| 475 |
|
| 476 | Ideally you will have done run-time testing specific to your change,
|
| 477 | and the patch series contains a set of kernel selftest for
|
| 478 | ``tools/testing/selftests/net`` or using the KUnit framework.
|
| 479 |
|
| 480 | You are expected to test your changes on top of the relevant networking
|
| 481 | tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
|
| 482 |
|
| 483 | patchwork checks
|
| 484 | ~~~~~~~~~~~~~~~~
|
| 485 |
|
| 486 | Checks in patchwork are mostly simple wrappers around existing kernel
|
| 487 | scripts, the sources are available at:
|
| 488 |
|
| 489 | https://github.com/linux-netdev/nipa/tree/master/tests
|
| 490 |
|
| 491 | **Do not** post your patches just to run them through the checks.
|
| 492 | You must ensure that your patches are ready by testing them locally
|
| 493 | before posting to the mailing list. The patchwork build bot instance
|
| 494 | gets overloaded very easily and netdev@vger really doesn't need more
|
| 495 | traffic if we can help it.
|
| 496 |
|
| 497 | netdevsim
|
| 498 | ~~~~~~~~~
|
| 499 |
|
| 500 | ``netdevsim`` is a test driver which can be used to exercise driver
|
| 501 | configuration APIs without requiring capable hardware.
|
| 502 | Mock-ups and tests based on ``netdevsim`` are encouraged when
|
| 503 | adding new APIs with complex logic in the stack. The tests should
|
| 504 | be written so that they can run both against ``netdevsim`` and a real
|
| 505 | device (see ``tools/testing/selftests/drivers/net/README.rst``).
|
| 506 | ``netdevsim``-only tests should focus on testing corner cases
|
| 507 | and failure paths in the core which are hard to exercise with a real driver.
|
| 508 |
|
| 509 | ``netdevsim`` in itself is **not** considered
|
| 510 | a use case/user. You must also implement the new APIs in a real driver.
|
| 511 |
|
| 512 | We give no guarantees that ``netdevsim`` won't change in the future
|
| 513 | in a way which would break what would normally be considered uAPI.
|
| 514 |
|
| 515 | ``netdevsim`` is reserved for use by upstream tests only, so any
|
| 516 | new ``netdevsim`` features must be accompanied by selftests under
|
| 517 | ``tools/testing/selftests/``.
|
| 518 |
|
| 519 | Supported status for drivers
|
| 520 | ----------------------------
|
| 521 |
|
| 522 | |
| 523 |
|
| 524 | Netdev defines additional requirements for drivers which want to acquire
|
| 525 | the ``Supported`` status in the MAINTAINERS file. ``Supported`` drivers must
|
| 526 | be running all upstream driver tests and reporting the results twice a day.
|
| 527 | Drivers which do not comply with this requirement should use the ``Maintained``
|
| 528 | status. There is currently no difference in how ``Supported`` and ``Maintained``
|
| 529 | drivers are treated upstream.
|
| 530 |
|
| 531 | The exact rules a driver must follow to acquire the ``Supported`` status:
|
| 532 |
|
| 533 | 1. Must run all tests under ``drivers/net`` and ``drivers/net/hw`` targets
|
| 534 | of Linux selftests. Running and reporting private / internal tests is
|
| 535 | also welcome, but upstream tests are a must.
|
| 536 |
|
| 537 | 2. The minimum run frequency is once every 12 hours. Must test the
|
| 538 | designated branch from the selected branch feed. Note that branches
|
| 539 | are auto-constructed and exposed to intentional malicious patch posting,
|
| 540 | so the test systems must be isolated.
|
| 541 |
|
| 542 | 3. Drivers supporting multiple generations of devices must test at
|
| 543 | least one device from each generation. A testbed manifest (exact
|
| 544 | format TBD) should describe the device models tested.
|
| 545 |
|
| 546 | 4. The tests must run reliably, if multiple branches are skipped or tests
|
| 547 | are failing due to execution environment problems the ``Supported``
|
| 548 | status will be withdrawn.
|
| 549 |
|
| 550 | 5. Test failures due to bugs either in the driver or the test itself,
|
| 551 | or lack of support for the feature the test is targeting are
|
| 552 | *not* a basis for losing the ``Supported`` status.
|
| 553 |
|
| 554 | netdev CI will maintain an official page of supported devices, listing their
|
| 555 | recent test results.
|
| 556 |
|
| 557 | The driver maintainer may arrange for someone else to run the test,
|
| 558 | there is no requirement for the person listed as maintainer (or their
|
| 559 | employer) to be responsible for running the tests. Collaboration between
|
| 560 | vendors, hosting GH CI, other repos under linux-netdev, etc. is most welcome.
|
| 561 |
|
| 562 | See https://github.com/linux-netdev/nipa/wiki for more information about
|
| 563 | netdev CI. Feel free to reach out to maintainers or the list with any questions.
|
| 564 |
|
| 565 | Reviewer guidance
|
| 566 | -----------------
|
| 567 |
|
| 568 | Reviewing other people's patches on the list is highly encouraged,
|
| 569 | regardless of the level of expertise. For general guidance and
|
| 570 | helpful tips please see :ref:`development_advancedtopics_reviews`.
|
| 571 |
|
| 572 | It's safe to assume that netdev maintainers know the community and the level
|
| 573 | of expertise of the reviewers. The reviewers should not be concerned about
|
| 574 | their comments impeding or derailing the patch flow. A Reviewed-by tag
|
| 575 | is understood to mean "I have reviewed this code to the best of my ability"
|
| 576 | rather than "I can attest this code is correct".
|
| 577 |
|
| 578 | Reviewers are highly encouraged to do more in-depth review of submissions
|
| 579 | and not focus exclusively on process issues, trivial or subjective
|
| 580 | matters like code formatting, tags etc.
|
| 581 |
|
| 582 | Testimonials / feedback
|
| 583 | -----------------------
|
| 584 |
|
| 585 | Some companies use peer feedback in employee performance reviews.
|
| 586 | Please feel free to request feedback from netdev maintainers,
|
| 587 | especially if you spend significant amount of time reviewing code
|
| 588 | and go out of your way to improve shared infrastructure.
|
| 589 |
|
| 590 | The feedback must be requested by you, the contributor, and will always
|
| 591 | be shared with you (even if you request for it to be submitted to your
|
| 592 | manager).
|