1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 .. _netdev-FAQ: 3 .. _netdev-FAQ:
4 4
5 ============================= !! 5 ==========
6 Networking subsystem (netdev) !! 6 netdev FAQ
7 ============================= !! 7 ==========
8 8
9 tl;dr 9 tl;dr
10 ----- 10 -----
11 11
12 - designate your patch to a tree - ``[PATCH n 12 - designate your patch to a tree - ``[PATCH net]`` or ``[PATCH net-next]``
13 - for fixes the ``Fixes:`` tag is required, r 13 - for fixes the ``Fixes:`` tag is required, regardless of the tree
14 - don't post large series (> 15 patches), bre 14 - don't post large series (> 15 patches), break them up
15 - don't repost your patches within one 24h pe 15 - don't repost your patches within one 24h period
16 - reverse xmas tree 16 - reverse xmas tree
17 17
18 netdev !! 18 What is netdev?
19 ------ !! 19 ---------------
20 !! 20 It is a mailing list for all network-related Linux stuff. This
21 netdev is a mailing list for all network-relat <<
22 includes anything found under net/ (i.e. core 21 includes anything found under net/ (i.e. core code like IPv6) and
23 drivers/net (i.e. hardware specific drivers) i 22 drivers/net (i.e. hardware specific drivers) in the Linux source tree.
24 23
25 Note that some subsystems (e.g. wireless drive 24 Note that some subsystems (e.g. wireless drivers) which have a high
26 volume of traffic have their own specific mail !! 25 volume of traffic have their own specific mailing lists.
27 26
28 Like many other Linux mailing lists, the netde !! 27 The netdev list is managed (like many other Linux mailing lists) through
29 kernel.org with archives available at https:// !! 28 VGER (http://vger.kernel.org/) with archives available at
>> 29 https://lore.kernel.org/netdev/
30 30
31 Aside from subsystems like those mentioned abo 31 Aside from subsystems like those mentioned above, all network-related
32 Linux development (i.e. RFC, review, comments, 32 Linux development (i.e. RFC, review, comments, etc.) takes place on
33 netdev. 33 netdev.
34 34
35 Development cycle !! 35 How do the changes posted to netdev make their way into Linux?
36 ----------------- !! 36 --------------------------------------------------------------
>> 37 There are always two trees (git repositories) in play. Both are
>> 38 driven by David Miller, the main network maintainer. There is the
>> 39 ``net`` tree, and the ``net-next`` tree. As you can probably guess from
>> 40 the names, the ``net`` tree is for fixes to existing code already in the
>> 41 mainline tree from Linus, and ``net-next`` is where the new code goes
>> 42 for the future release. You can find the trees here:
>> 43
>> 44 - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git
>> 45 - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git
>> 46
>> 47 How do I indicate which tree (net vs. net-next) my patch should be in?
>> 48 ----------------------------------------------------------------------
>> 49 To help maintainers and CI bots you should explicitly mark which tree
>> 50 your patch is targeting. Assuming that you use git, use the prefix
>> 51 flag::
37 52
38 Here is a bit of background information on !! 53 git format-patch --subject-prefix='PATCH net-next' start..finish
>> 54
>> 55 Use ``net`` instead of ``net-next`` (always lower case) in the above for
>> 56 bug-fix ``net`` content.
>> 57
>> 58 How often do changes from these trees make it to the mainline Linus tree?
>> 59 -------------------------------------------------------------------------
>> 60 To understand this, you need to know a bit of background information on
39 the cadence of Linux development. Each new re 61 the cadence of Linux development. Each new release starts off with a
40 two week "merge window" where the main maintai 62 two week "merge window" where the main maintainers feed their new stuff
41 to Linus for merging into the mainline tree. 63 to Linus for merging into the mainline tree. After the two weeks, the
42 merge window is closed, and it is called/tagge 64 merge window is closed, and it is called/tagged ``-rc1``. No new
43 features get mainlined after this -- only fixe 65 features get mainlined after this -- only fixes to the rc1 content are
44 expected. After roughly a week of collecting 66 expected. After roughly a week of collecting fixes to the rc1 content,
45 rc2 is released. This repeats on a roughly we 67 rc2 is released. This repeats on a roughly weekly basis until rc7
46 (typically; sometimes rc6 if things are quiet, 68 (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. 69 state of churn), and a week after the last vX.Y-rcN was done, the
48 official vX.Y is released. 70 official vX.Y is released.
49 71
50 To find out where we are now in the cycle - lo !! 72 Relating that to netdev: At the beginning of the 2-week merge window,
51 page here: !! 73 the ``net-next`` tree will be closed - no new changes/features. The
52 !! 74 accumulated new content of the past ~10 weeks will be passed onto
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 -- 75 mainline/Linus via a pull request for vX.Y -- at the same time, the
78 ``net`` tree will start accumulating fixes for 76 ``net`` tree will start accumulating fixes for this pulled content
79 relating to vX.Y 77 relating to vX.Y
80 78
81 An announcement indicating when ``net-next`` h 79 An announcement indicating when ``net-next`` has been closed is usually
82 sent to netdev, but knowing the above, you can 80 sent to netdev, but knowing the above, you can predict that in advance.
83 81
84 .. warning:: 82 .. warning::
85 Do not send new ``net-next`` content to netd 83 Do not send new ``net-next`` content to netdev during the
86 period during which ``net-next`` tree is clo 84 period during which ``net-next`` tree is closed.
87 85
88 RFC patches sent for review only are obviously 86 RFC patches sent for review only are obviously welcome at any time
89 (use ``--subject-prefix='RFC net-next'`` with 87 (use ``--subject-prefix='RFC net-next'`` with ``git format-patch``).
90 88
91 Shortly after the two weeks have passed (and v 89 Shortly after the two weeks have passed (and vX.Y-rc1 is released), the
92 tree for ``net-next`` reopens to collect conte 90 tree for ``net-next`` reopens to collect content for the next (vX.Y+1)
93 release. 91 release.
94 92
95 If you aren't subscribed to netdev and/or are 93 If you aren't subscribed to netdev and/or are simply unsure if
96 ``net-next`` has re-opened yet, simply check t 94 ``net-next`` has re-opened yet, simply check the ``net-next`` git
97 repository link above for any new networking-r 95 repository link above for any new networking-related commits. You may
98 also check the following website for the curre 96 also check the following website for the current status:
99 97
100 https://netdev.bots.linux.dev/net-next.html !! 98 http://vger.kernel.org/~davem/net-next.html
101 99
102 The ``net`` tree continues to collect fixes fo 100 The ``net`` tree continues to collect fixes for the vX.Y content, and is
103 fed back to Linus at regular (~weekly) interva 101 fed back to Linus at regular (~weekly) intervals. Meaning that the
104 focus for ``net`` is on stabilization and bug 102 focus for ``net`` is on stabilization and bug fixes.
105 103
106 Finally, the vX.Y gets released, and the whole 104 Finally, the vX.Y gets released, and the whole cycle starts over.
107 105
108 netdev patch review !! 106 So where are we now in this cycle?
109 ------------------- !! 107 ----------------------------------
110 108
111 .. _patch_status: !! 109 Load the mainline (Linus) page here:
112 110
113 Patch status !! 111 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
114 ~~~~~~~~~~~~ !! 112
>> 113 and note the top of the "tags" section. If it is rc1, it is early in
>> 114 the dev cycle. If it was tagged rc7 a week ago, then a release is
>> 115 probably imminent. If the most recent tag is a final release tag
>> 116 (without an ``-rcN`` suffix) - we are most likely in a merge window
>> 117 and ``net-next`` is closed.
115 118
116 Status of a patch can be checked by looking at !! 119 How can I tell the status of a patch I've sent?
117 queue for netdev: !! 120 -----------------------------------------------
>> 121 Start by looking at the main patchworks queue for netdev:
118 122
119 https://patchwork.kernel.org/project/netdevb 123 https://patchwork.kernel.org/project/netdevbpf/list/
120 124
121 The "State" field will tell you exactly where 125 The "State" field will tell you exactly where things are at with your
122 patch: !! 126 patch. Patches are indexed by the ``Message-ID`` header of the emails
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 127 which carried them so if you have trouble finding your patch append
154 the value of ``Message-ID`` to the URL above. 128 the value of ``Message-ID`` to the URL above.
155 129
156 Updating patch status !! 130 How long before my patch is accepted?
157 ~~~~~~~~~~~~~~~~~~~~~ !! 131 -------------------------------------
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 132 Generally speaking, the patches get triaged quickly (in less than
193 48h). But be patient, if your patch is active 133 48h). But be patient, if your patch is active in patchwork (i.e. it's
194 listed on the project's patch list) the chance 134 listed on the project's patch list) the chances it was missed are close to zero.
>> 135 Asking the maintainer for status updates on your
>> 136 patch is a good way to ensure your patch is ignored or pushed to the
>> 137 bottom of the priority list.
>> 138
>> 139 Should I directly update patchwork state of my own patches?
>> 140 -----------------------------------------------------------
>> 141 It may be tempting to help the maintainers and update the state of your
>> 142 own patches when you post a new version or spot a bug. Please do not do that.
>> 143 Interfering with the patch status on patchwork will only cause confusion. Leave
>> 144 it to the maintainer to figure out what is the most recent and current
>> 145 version that should be applied. If there is any doubt, the maintainer
>> 146 will reply and ask what should be done.
195 147
196 The high volume of development on netdev makes !! 148 How do I divide my work into patches?
197 from discussions relatively quickly. New comme !! 149 -------------------------------------
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 150
218 Patches :ref:`marked<patch_status>` as ``Chang !! 151 Put yourself in the shoes of the reviewer. Each patch is read separately
219 to be revised. The new version should come wit !! 152 and therefore should constitute a comprehensible step towards your stated
220 preferably including links to previous posting !! 153 goal.
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 154
242 Partial resends !! 155 Avoid sending series longer than 15 patches. Larger series takes longer
243 ~~~~~~~~~~~~~~~ !! 156 to review as reviewers will defer looking at it until they find a large
>> 157 chunk of time. A small series can be reviewed in a short time, so Maintainers
>> 158 just do it. As a result, a sequence of smaller series gets merged quicker and
>> 159 with better review coverage. Re-posting large series also increases the mailing
>> 160 list traffic.
244 161
245 Please always resend the entire patch series a !! 162 I made changes to only a few patches in a patch series should I resend only those changed?
>> 163 ------------------------------------------------------------------------------------------
>> 164 No, please resend the entire patch series and make sure you do number your
246 patches such that it is clear this is the late 165 patches such that it is clear this is the latest and greatest set of patches
247 that can be applied. Do not try to resend just !! 166 that can be applied.
248 167
249 Handling misapplied patches !! 168 I have received review feedback, when should I post a revised version of the patches?
250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ !! 169 -------------------------------------------------------------------------------------
>> 170 Allow at least 24 hours to pass between postings. This will ensure reviewers
>> 171 from all geographical locations have a chance to chime in. Do not wait
>> 172 too long (weeks) between postings either as it will make it harder for reviewers
>> 173 to recall all the context.
251 174
252 Occasionally a patch series gets applied befor !! 175 Make sure you address all the feedback in your new posting. Do not post a new
253 or the wrong version of a series gets applied. !! 176 version of the code if the discussion about the previous version is still
>> 177 ongoing, unless directly instructed by a reviewer.
254 178
255 Making the patch disappear once it is pushed o !! 179 I submitted multiple versions of a patch series and it looks like a version other than the last one has been accepted, what should I do?
256 history in netdev trees is immutable. !! 180 ----------------------------------------------------------------------------------------------------------------------------------------
>> 181 There is no revert possible, once it is pushed out, it stays like that.
257 Please send incremental versions on top of wha 182 Please send incremental versions on top of what has been merged in order to fix
258 the patches the way they would look like if yo 183 the patches the way they would look like if your latest patch series was to be
259 merged. 184 merged.
260 185
261 In cases where full revert is needed the rever !! 186 Are there special rules regarding stable submissions on netdev?
262 as a patch to the list with a commit message e !! 187 ---------------------------------------------------------------
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 188 While it used to be the case that netdev submissions were not supposed
270 to carry explicit ``CC: stable@vger.kernel.org 189 to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
271 the case today. Please follow the standard sta 190 the case today. Please follow the standard stable rules in
272 :ref:`Documentation/process/stable-kernel-rule 191 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
273 and make sure you include appropriate Fixes ta 192 and make sure you include appropriate Fixes tags!
274 193
275 Security fixes !! 194 Is the comment style convention different for the networking content?
276 ~~~~~~~~~~~~~~ !! 195 ---------------------------------------------------------------------
>> 196 Yes, in a largely trivial way. Instead of this::
>> 197
>> 198 /*
>> 199 * foobar blah blah blah
>> 200 * another line of text
>> 201 */
>> 202
>> 203 it is requested that you make it look like this::
>> 204
>> 205 /* foobar blah blah blah
>> 206 * another line of text
>> 207 */
>> 208
>> 209 What is "reverse xmas tree"?
>> 210 ----------------------------
>> 211
>> 212 Netdev has a convention for ordering local variables in functions.
>> 213 Order the variable declaration lines longest to shortest, e.g.::
>> 214
>> 215 struct scatterlist *sg;
>> 216 struct sk_buff *skb;
>> 217 int err, i;
>> 218
>> 219 If there are dependencies between the variables preventing the ordering
>> 220 move the initialization out of line.
>> 221
>> 222 I am working in existing code which uses non-standard formatting. Which formatting should I use?
>> 223 ------------------------------------------------------------------------------------------------
>> 224 Make your code follow the most recent guidelines, so that eventually all code
>> 225 in the domain of netdev is in the preferred format.
277 226
278 Do not email netdev maintainers directly if yo !! 227 I found a bug that might have possible security implications or similar. Should I mail the main netdev maintainer off-list?
279 a bug that might have possible security implic !! 228 ---------------------------------------------------------------------------------------------------------------------------
280 The current netdev maintainer has consistently !! 229 No. The current netdev maintainer has consistently requested that
281 people use the mailing lists and not reach out 230 people use the mailing lists and not reach out directly. If you aren't
282 OK with that, then perhaps consider mailing se 231 OK with that, then perhaps consider mailing security@kernel.org or
283 reading about http://oss-security.openwall.org 232 reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
284 as possible alternative mechanisms. 233 as possible alternative mechanisms.
285 234
>> 235 What level of testing is expected before I submit my change?
>> 236 ------------------------------------------------------------
>> 237 At the very minimum your changes must survive an ``allyesconfig`` and an
>> 238 ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
286 239
287 Co-posting changes to user space components !! 240 Ideally you will have done run-time testing specific to your change,
288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ !! 241 and the patch series contains a set of kernel selftest for
>> 242 ``tools/testing/selftests/net`` or using the KUnit framework.
289 243
>> 244 You are expected to test your changes on top of the relevant networking
>> 245 tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
>> 246
>> 247 How do I post corresponding changes to user space components?
>> 248 -------------------------------------------------------------
290 User space code exercising kernel features sho 249 User space code exercising kernel features should be posted
291 alongside kernel patches. This gives reviewers 250 alongside kernel patches. This gives reviewers a chance to see
292 how any new interface is used and how well it 251 how any new interface is used and how well it works.
293 252
294 When user space tools reside in the kernel rep 253 When user space tools reside in the kernel repo itself all changes
295 should generally come as one series. If series 254 should generally come as one series. If series becomes too large
296 or the user space project is not reviewed on n 255 or the user space project is not reviewed on netdev include a link
297 to a public repo where user space patches can 256 to a public repo where user space patches can be seen.
298 257
299 In case user space tooling lives in a separate 258 In case user space tooling lives in a separate repository but is
300 reviewed on netdev (e.g. patches to ``iproute 259 reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and
301 user space patches should form separate series 260 user space patches should form separate series (threads) when posted
302 to the mailing list, e.g.:: 261 to the mailing list, e.g.::
303 262
304 [PATCH net-next 0/3] net: some feature cover 263 [PATCH net-next 0/3] net: some feature cover letter
305 └─ [PATCH net-next 1/3] net: some featu 264 └─ [PATCH net-next 1/3] net: some feature prep
306 └─ [PATCH net-next 2/3] net: some featu 265 └─ [PATCH net-next 2/3] net: some feature do it
307 └─ [PATCH net-next 3/3] selftest: net: 266 └─ [PATCH net-next 3/3] selftest: net: some feature
308 267
309 [PATCH iproute2-next] ip: add support for so 268 [PATCH iproute2-next] ip: add support for some feature
310 269
311 Posting as one thread is discouraged because i 270 Posting as one thread is discouraged because it confuses patchwork
312 (as of patchwork 2.2.2). 271 (as of patchwork 2.2.2).
313 272
314 Preparing changes !! 273 Can I reproduce the checks from patchwork on my local machine?
315 ----------------- !! 274 --------------------------------------------------------------
>> 275
>> 276 Checks in patchwork are mostly simple wrappers around existing kernel
>> 277 scripts, the sources are available at:
>> 278
>> 279 https://github.com/kuba-moo/nipa/tree/master/tests
>> 280
>> 281 Running all the builds and checks locally is a pain, can I post my patches and have the patchwork bot validate them?
>> 282 --------------------------------------------------------------------------------------------------------------------
316 283
317 Attention to detail is important. Re-read you !! 284 No, you must ensure that your patches are ready by testing them locally
>> 285 before posting to the mailing list. The patchwork build bot instance
>> 286 gets overloaded very easily and netdev@vger really doesn't need more
>> 287 traffic if we can help it.
>> 288
>> 289 netdevsim is great, can I extend it for my out-of-tree tests?
>> 290 -------------------------------------------------------------
>> 291
>> 292 No, ``netdevsim`` is a test vehicle solely for upstream tests.
>> 293 (Please add your tests under ``tools/testing/selftests/``.)
>> 294
>> 295 We also give no guarantees that ``netdevsim`` won't change in the future
>> 296 in a way which would break what would normally be considered uAPI.
>> 297
>> 298 Is netdevsim considered a "user" of an API?
>> 299 -------------------------------------------
>> 300
>> 301 Linux kernel has a long standing rule that no API should be added unless
>> 302 it has a real, in-tree user. Mock-ups and tests based on ``netdevsim`` are
>> 303 strongly encouraged when adding new APIs, but ``netdevsim`` in itself
>> 304 is **not** considered a use case/user.
>> 305
>> 306 Any other tips to help ensure my net/net-next patch gets OK'd?
>> 307 --------------------------------------------------------------
>> 308 Attention to detail. Re-read your own work as if you were the
318 reviewer. You can start with using ``checkpat 309 reviewer. You can start with using ``checkpatch.pl``, perhaps even with
319 the ``--strict`` flag. But do not be mindless 310 the ``--strict`` flag. But do not be mindlessly robotic in doing so.
320 If your change is a bug fix, make sure your co 311 If your change is a bug fix, make sure your commit log indicates the
321 end-user visible symptom, the underlying reaso 312 end-user visible symptom, the underlying reason as to why it happens,
322 and then if necessary, explain why the fix pro 313 and then if necessary, explain why the fix proposed is the best way to
323 get things done. Don't mangle whitespace, and 314 get things done. Don't mangle whitespace, and as is common, don't
324 mis-indent function arguments that span multip 315 mis-indent function arguments that span multiple lines. If it is your
325 first patch, mail it to yourself so you can te 316 first patch, mail it to yourself so you can test apply it to an
326 unpatched tree to confirm infrastructure didn' 317 unpatched tree to confirm infrastructure didn't mangle it.
327 318
328 Finally, go back and read 319 Finally, go back and read
329 :ref:`Documentation/process/submitting-patches 320 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
330 to be sure you are not repeating some common m 321 to be sure you are not repeating some common mistake documented there.
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). <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.