~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/process/maintainer-netdev.rst

Version: ~ [ linux-6.11.5 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.58 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.114 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.169 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.228 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.284 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.322 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.9 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/process/maintainer-netdev.rst (Version linux-6.11.5) and /Documentation/process/maintainer-netdev.rst (Version linux-5.0.21)


  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).                                         
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php