1 .. SPDX-License-Identifier: GPL-2.0
5 =============================
6 Networking subsystem (netdev)
7 =============================
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
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.
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.
28 The netdev list is managed (like many other Linux mailing lists) through
29 VGER (http://vger.kernel.org/) with archives available at
30 https://lore.kernel.org/netdev/
32 Aside from subsystems like those mentioned above, all network-related
33 Linux development (i.e. RFC, review, comments, etc.) takes place on
39 Here is a bit of background information on
40 the cadence of Linux development. Each new release starts off with a
41 two week "merge window" where the main maintainers feed their new stuff
42 to Linus for merging into the mainline tree. After the two weeks, the
43 merge window is closed, and it is called/tagged ``-rc1``. No new
44 features get mainlined after this -- only fixes to the rc1 content are
45 expected. After roughly a week of collecting fixes to the rc1 content,
46 rc2 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
48 state of churn), and a week after the last vX.Y-rcN was done, the
49 official vX.Y is released.
51 To find out where we are now in the cycle - load the mainline (Linus)
54 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
56 and note the top of the "tags" section. If it is rc1, it is early in
57 the dev cycle. If it was tagged rc7 a week ago, then a release is
58 probably imminent. If the most recent tag is a final release tag
59 (without an ``-rcN`` suffix) - we are most likely in a merge window
60 and ``net-next`` is closed.
62 git trees and patch flow
63 ------------------------
65 There are two networking trees (git repositories) in play. Both are
66 driven by David Miller, the main network maintainer. There is the
67 ``net`` tree, and the ``net-next`` tree. As you can probably guess from
68 the names, the ``net`` tree is for fixes to existing code already in the
69 mainline tree from Linus, and ``net-next`` is where the new code goes
70 for the future release. You can find the trees here:
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
75 Relating that to kernel development: At the beginning of the 2-week
76 merge window, the ``net-next`` tree will be closed - no new changes/features.
77 The accumulated new content of the past ~10 weeks will be passed onto
78 mainline/Linus via a pull request for vX.Y -- at the same time, the
79 ``net`` tree will start accumulating fixes for this pulled content
82 An announcement indicating when ``net-next`` has been closed is usually
83 sent to netdev, but knowing the above, you can predict that in advance.
86 Do not send new ``net-next`` content to netdev during the
87 period during which ``net-next`` tree is closed.
89 RFC patches sent for review only are obviously welcome at any time
90 (use ``--subject-prefix='RFC net-next'`` with ``git format-patch``).
92 Shortly after the two weeks have passed (and vX.Y-rc1 is released), the
93 tree for ``net-next`` reopens to collect content for the next (vX.Y+1)
96 If 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
98 repository link above for any new networking-related commits. You may
99 also check the following website for the current status:
101 https://patchwork.hopto.org/net-next.html
103 The ``net`` tree continues to collect fixes for the vX.Y content, and is
104 fed back to Linus at regular (~weekly) intervals. Meaning that the
105 focus for ``net`` is on stabilization and bug fixes.
107 Finally, the vX.Y gets released, and the whole cycle starts over.
117 Status of a patch can be checked by looking at the main patchwork
120 https://patchwork.kernel.org/project/netdevbpf/list/
122 The "State" field will tell you exactly where things are at with your
123 patch. Patches are indexed by the ``Message-ID`` header of the emails
124 which carried them so if you have trouble finding your patch append
125 the value of ``Message-ID`` to the URL above.
127 Updating patch status
128 ~~~~~~~~~~~~~~~~~~~~~
130 Contributors and reviewers do not have the permissions to update patch
131 state directly in patchwork. Patchwork doesn't expose much information
132 about the history of the state of patches, therefore having multiple
133 people update the state leads to confusion.
135 Instead of delegating patchwork permissions netdev uses a simple mail
136 bot which looks for special commands/lines within the emails sent to
137 the mailing list. For example to mark a series as Changes Requested
138 one needs to send the following line anywhere in the email thread::
140 pw-bot: changes-requested
142 As a result the bot will set the entire series to Changes Requested.
143 This may be useful when author discovers a bug in their own series
144 and wants to prevent it from getting applied.
146 The use of the bot is entirely optional, if in doubt ignore its existence
147 completely. Maintainers will classify and update the state of the patches
148 themselves. No email should ever be sent to the list with the main purpose
149 of communicating with the bot, the bot commands should be seen as metadata.
151 The use of the bot is restricted to authors of the patches (the ``From:``
152 header on patch submission and command must match!), maintainers of
153 the modified code according to the MAINTAINERS file (again, ``From:``
154 must match the MAINTAINERS entry) and a handful of senior reviewers.
156 Bot records its activity here:
158 https://patchwork.hopto.org/pw-bot.html
163 Generally speaking, the patches get triaged quickly (in less than
164 48h). But be patient, if your patch is active in patchwork (i.e. it's
165 listed on the project's patch list) the chances it was missed are close to zero.
166 Asking the maintainer for status updates on your
167 patch is a good way to ensure your patch is ignored or pushed to the
168 bottom of the priority list.
170 .. _Changes requested:
175 Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
176 to be revised. The new version should come with a change log,
177 preferably including links to previous postings, for example::
179 [PATCH net-next v3] net: make cows go moo
181 Even users who don't drink milk appreciate hearing the cows go "moo".
183 The amount of mooing will depend on packet rate so should match
184 the diurnal cycle quite well.
186 Signed-of-by: Joe Defarmer <joe@barn.org>
189 - add a note about time-of-day mooing fluctuation to the commit message
190 v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
191 - fix missing argument in kernel doc for netif_is_bovine()
192 - fix memory leak in netdev_register_cow()
193 v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/
195 The commit message should be revised to answer any questions reviewers
196 had to ask in previous discussions. Occasionally the update of
197 the commit message will be the only change in the new version.
202 Please always resend the entire patch series and make sure you do number your
203 patches such that it is clear this is the latest and greatest set of patches
204 that can be applied. Do not try to resend just the patches which changed.
206 Handling misapplied patches
207 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
209 Occasionally a patch series gets applied before receiving critical feedback,
210 or the wrong version of a series gets applied.
212 Making the patch disappear once it is pushed out is not possible, the commit
213 history in netdev trees is immutable.
214 Please send incremental versions on top of what has been merged in order to fix
215 the patches the way they would look like if your latest patch series was to be
218 In cases where full revert is needed the revert has to be submitted
219 as a patch to the list with a commit message explaining the technical
220 problems with the reverted commit. Reverts should be used as a last resort,
221 when original change is completely wrong; incremental fixes are preferred.
226 While it used to be the case that netdev submissions were not supposed
227 to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
228 the case today. Please follow the standard stable rules in
229 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
230 and make sure you include appropriate Fixes tags!
235 Do not email netdev maintainers directly if you think you discovered
236 a bug that might have possible security implications.
237 The current netdev maintainer has consistently requested that
238 people use the mailing lists and not reach out directly. If you aren't
239 OK with that, then perhaps consider mailing security@kernel.org or
240 reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
241 as possible alternative mechanisms.
244 Co-posting changes to user space components
245 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
247 User space code exercising kernel features should be posted
248 alongside kernel patches. This gives reviewers a chance to see
249 how any new interface is used and how well it works.
251 When user space tools reside in the kernel repo itself all changes
252 should generally come as one series. If series becomes too large
253 or the user space project is not reviewed on netdev include a link
254 to a public repo where user space patches can be seen.
256 In case user space tooling lives in a separate repository but is
257 reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and
258 user space patches should form separate series (threads) when posted
259 to the mailing list, e.g.::
261 [PATCH net-next 0/3] net: some feature cover letter
262 └─ [PATCH net-next 1/3] net: some feature prep
263 └─ [PATCH net-next 2/3] net: some feature do it
264 └─ [PATCH net-next 3/3] selftest: net: some feature
266 [PATCH iproute2-next] ip: add support for some feature
268 Posting as one thread is discouraged because it confuses patchwork
269 (as of patchwork 2.2.2).
274 Attention to detail is important. Re-read your own work as if you were the
275 reviewer. You can start with using ``checkpatch.pl``, perhaps even with
276 the ``--strict`` flag. But do not be mindlessly robotic in doing so.
277 If your change is a bug fix, make sure your commit log indicates the
278 end-user visible symptom, the underlying reason as to why it happens,
279 and then if necessary, explain why the fix proposed is the best way to
280 get things done. Don't mangle whitespace, and as is common, don't
281 mis-indent function arguments that span multiple lines. If it is your
282 first patch, mail it to yourself so you can test apply it to an
283 unpatched tree to confirm infrastructure didn't mangle it.
285 Finally, go back and read
286 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
287 to be sure you are not repeating some common mistake documented there.
289 Indicating target tree
290 ~~~~~~~~~~~~~~~~~~~~~~
292 To help maintainers and CI bots you should explicitly mark which tree
293 your patch is targeting. Assuming that you use git, use the prefix
296 git format-patch --subject-prefix='PATCH net-next' start..finish
298 Use ``net`` instead of ``net-next`` (always lower case) in the above for
299 bug-fix ``net`` content.
301 Dividing work into patches
302 ~~~~~~~~~~~~~~~~~~~~~~~~~~
304 Put yourself in the shoes of the reviewer. Each patch is read separately
305 and therefore should constitute a comprehensible step towards your stated
308 Avoid sending series longer than 15 patches. Larger series takes longer
309 to review as reviewers will defer looking at it until they find a large
310 chunk of time. A small series can be reviewed in a short time, so Maintainers
311 just do it. As a result, a sequence of smaller series gets merged quicker and
312 with better review coverage. Re-posting large series also increases the mailing
318 Comment style convention is slightly different for networking and most of
319 the tree. Instead of this::
322 * foobar blah blah blah
323 * another line of text
326 it is requested that you make it look like this::
328 /* foobar blah blah blah
329 * another line of text
332 Local variable ordering ("reverse xmas tree", "RCS")
333 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
335 Netdev has a convention for ordering local variables in functions.
336 Order the variable declaration lines longest to shortest, e.g.::
338 struct scatterlist *sg;
342 If there are dependencies between the variables preventing the ordering
343 move the initialization out of line.
348 When working in existing code which uses nonstandard formatting make
349 your code follow the most recent guidelines, so that eventually all code
350 in the domain of netdev is in the preferred format.
352 Resending after review
353 ~~~~~~~~~~~~~~~~~~~~~~
355 Allow at least 24 hours to pass between postings. This will ensure reviewers
356 from all geographical locations have a chance to chime in. Do not wait
357 too long (weeks) between postings either as it will make it harder for reviewers
358 to recall all the context.
360 Make sure you address all the feedback in your new posting. Do not post a new
361 version of the code if the discussion about the previous version is still
362 ongoing, unless directly instructed by a reviewer.
364 The new version of patches should be posted as a separate thread,
365 not as a reply to the previous posting. Change log should include a link
366 to the previous posting (see :ref:`Changes requested`).
371 Expected level of testing
372 ~~~~~~~~~~~~~~~~~~~~~~~~~
374 At the very minimum your changes must survive an ``allyesconfig`` and an
375 ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
377 Ideally you will have done run-time testing specific to your change,
378 and the patch series contains a set of kernel selftest for
379 ``tools/testing/selftests/net`` or using the KUnit framework.
381 You are expected to test your changes on top of the relevant networking
382 tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
387 Checks in patchwork are mostly simple wrappers around existing kernel
388 scripts, the sources are available at:
390 https://github.com/kuba-moo/nipa/tree/master/tests
392 **Do not** post your patches just to run them through the checks.
393 You must ensure that your patches are ready by testing them locally
394 before posting to the mailing list. The patchwork build bot instance
395 gets overloaded very easily and netdev@vger really doesn't need more
396 traffic if we can help it.
401 ``netdevsim`` is a test driver which can be used to exercise driver
402 configuration APIs without requiring capable hardware.
403 Mock-ups and tests based on ``netdevsim`` are strongly encouraged when
404 adding new APIs, but ``netdevsim`` in itself is **not** considered
405 a use case/user. You must also implement the new APIs in a real driver.
407 We give no guarantees that ``netdevsim`` won't change in the future
408 in a way which would break what would normally be considered uAPI.
410 ``netdevsim`` is reserved for use by upstream tests only, so any
411 new ``netdevsim`` features must be accompanied by selftests under
412 ``tools/testing/selftests/``.
414 Testimonials / feedback
415 -----------------------
417 Some companies use peer feedback in employee performance reviews.
418 Please feel free to request feedback from netdev maintainers,
419 especially if you spend significant amount of time reviewing code
420 and go out of your way to improve shared infrastructure.
422 The feedback must be requested by you, the contributor, and will always
423 be shared with you (even if you request for it to be submitted to your