0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 .. _netdev-FAQ:
0004
0005 ==========
0006 netdev FAQ
0007 ==========
0008
0009 tl;dr
0010 -----
0011
0012 - designate your patch to a tree - ``[PATCH net]`` or ``[PATCH net-next]``
0013 - for fixes the ``Fixes:`` tag is required, regardless of the tree
0014 - don't post large series (> 15 patches), break them up
0015 - don't repost your patches within one 24h period
0016 - reverse xmas tree
0017
0018 What is netdev?
0019 ---------------
0020 It is a mailing list for all network-related Linux stuff. This
0021 includes anything found under net/ (i.e. core code like IPv6) and
0022 drivers/net (i.e. hardware specific drivers) in the Linux source tree.
0023
0024 Note that some subsystems (e.g. wireless drivers) which have a high
0025 volume of traffic have their own specific mailing lists.
0026
0027 The netdev list is managed (like many other Linux mailing lists) through
0028 VGER (http://vger.kernel.org/) with archives available at
0029 https://lore.kernel.org/netdev/
0030
0031 Aside from subsystems like those mentioned above, all network-related
0032 Linux development (i.e. RFC, review, comments, etc.) takes place on
0033 netdev.
0034
0035 How do the changes posted to netdev make their way into Linux?
0036 --------------------------------------------------------------
0037 There are always two trees (git repositories) in play. Both are
0038 driven by David Miller, the main network maintainer. There is the
0039 ``net`` tree, and the ``net-next`` tree. As you can probably guess from
0040 the names, the ``net`` tree is for fixes to existing code already in the
0041 mainline tree from Linus, and ``net-next`` is where the new code goes
0042 for the future release. You can find the trees here:
0043
0044 - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git
0045 - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git
0046
0047 How do I indicate which tree (net vs. net-next) my patch should be in?
0048 ----------------------------------------------------------------------
0049 To help maintainers and CI bots you should explicitly mark which tree
0050 your patch is targeting. Assuming that you use git, use the prefix
0051 flag::
0052
0053 git format-patch --subject-prefix='PATCH net-next' start..finish
0054
0055 Use ``net`` instead of ``net-next`` (always lower case) in the above for
0056 bug-fix ``net`` content.
0057
0058 How often do changes from these trees make it to the mainline Linus tree?
0059 -------------------------------------------------------------------------
0060 To understand this, you need to know a bit of background information on
0061 the cadence of Linux development. Each new release starts off with a
0062 two week "merge window" where the main maintainers feed their new stuff
0063 to Linus for merging into the mainline tree. After the two weeks, the
0064 merge window is closed, and it is called/tagged ``-rc1``. No new
0065 features get mainlined after this -- only fixes to the rc1 content are
0066 expected. After roughly a week of collecting fixes to the rc1 content,
0067 rc2 is released. This repeats on a roughly weekly basis until rc7
0068 (typically; sometimes rc6 if things are quiet, or rc8 if things are in a
0069 state of churn), and a week after the last vX.Y-rcN was done, the
0070 official vX.Y is released.
0071
0072 Relating that to netdev: At the beginning of the 2-week merge window,
0073 the ``net-next`` tree will be closed - no new changes/features. The
0074 accumulated new content of the past ~10 weeks will be passed onto
0075 mainline/Linus via a pull request for vX.Y -- at the same time, the
0076 ``net`` tree will start accumulating fixes for this pulled content
0077 relating to vX.Y
0078
0079 An announcement indicating when ``net-next`` has been closed is usually
0080 sent to netdev, but knowing the above, you can predict that in advance.
0081
0082 .. warning::
0083 Do not send new ``net-next`` content to netdev during the
0084 period during which ``net-next`` tree is closed.
0085
0086 RFC patches sent for review only are obviously welcome at any time
0087 (use ``--subject-prefix='RFC net-next'`` with ``git format-patch``).
0088
0089 Shortly after the two weeks have passed (and vX.Y-rc1 is released), the
0090 tree for ``net-next`` reopens to collect content for the next (vX.Y+1)
0091 release.
0092
0093 If you aren't subscribed to netdev and/or are simply unsure if
0094 ``net-next`` has re-opened yet, simply check the ``net-next`` git
0095 repository link above for any new networking-related commits. You may
0096 also check the following website for the current status:
0097
0098 http://vger.kernel.org/~davem/net-next.html
0099
0100 The ``net`` tree continues to collect fixes for the vX.Y content, and is
0101 fed back to Linus at regular (~weekly) intervals. Meaning that the
0102 focus for ``net`` is on stabilization and bug fixes.
0103
0104 Finally, the vX.Y gets released, and the whole cycle starts over.
0105
0106 So where are we now in this cycle?
0107 ----------------------------------
0108
0109 Load the mainline (Linus) page here:
0110
0111 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
0112
0113 and note the top of the "tags" section. If it is rc1, it is early in
0114 the dev cycle. If it was tagged rc7 a week ago, then a release is
0115 probably imminent. If the most recent tag is a final release tag
0116 (without an ``-rcN`` suffix) - we are most likely in a merge window
0117 and ``net-next`` is closed.
0118
0119 How can I tell the status of a patch I've sent?
0120 -----------------------------------------------
0121 Start by looking at the main patchworks queue for netdev:
0122
0123 https://patchwork.kernel.org/project/netdevbpf/list/
0124
0125 The "State" field will tell you exactly where things are at with your
0126 patch. Patches are indexed by the ``Message-ID`` header of the emails
0127 which carried them so if you have trouble finding your patch append
0128 the value of ``Message-ID`` to the URL above.
0129
0130 How long before my patch is accepted?
0131 -------------------------------------
0132 Generally speaking, the patches get triaged quickly (in less than
0133 48h). But be patient, if your patch is active in patchwork (i.e. it's
0134 listed on the project's patch list) the chances it was missed are close to zero.
0135 Asking the maintainer for status updates on your
0136 patch is a good way to ensure your patch is ignored or pushed to the
0137 bottom of the priority list.
0138
0139 Should I directly update patchwork state of my own patches?
0140 -----------------------------------------------------------
0141 It may be tempting to help the maintainers and update the state of your
0142 own patches when you post a new version or spot a bug. Please do not do that.
0143 Interfering with the patch status on patchwork will only cause confusion. Leave
0144 it to the maintainer to figure out what is the most recent and current
0145 version that should be applied. If there is any doubt, the maintainer
0146 will reply and ask what should be done.
0147
0148 How do I divide my work into patches?
0149 -------------------------------------
0150
0151 Put yourself in the shoes of the reviewer. Each patch is read separately
0152 and therefore should constitute a comprehensible step towards your stated
0153 goal.
0154
0155 Avoid sending series longer than 15 patches. Larger series takes longer
0156 to review as reviewers will defer looking at it until they find a large
0157 chunk of time. A small series can be reviewed in a short time, so Maintainers
0158 just do it. As a result, a sequence of smaller series gets merged quicker and
0159 with better review coverage. Re-posting large series also increases the mailing
0160 list traffic.
0161
0162 I made changes to only a few patches in a patch series should I resend only those changed?
0163 ------------------------------------------------------------------------------------------
0164 No, please resend the entire patch series and make sure you do number your
0165 patches such that it is clear this is the latest and greatest set of patches
0166 that can be applied.
0167
0168 I have received review feedback, when should I post a revised version of the patches?
0169 -------------------------------------------------------------------------------------
0170 Allow at least 24 hours to pass between postings. This will ensure reviewers
0171 from all geographical locations have a chance to chime in. Do not wait
0172 too long (weeks) between postings either as it will make it harder for reviewers
0173 to recall all the context.
0174
0175 Make sure you address all the feedback in your new posting. Do not post a new
0176 version of the code if the discussion about the previous version is still
0177 ongoing, unless directly instructed by a reviewer.
0178
0179 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?
0180 ----------------------------------------------------------------------------------------------------------------------------------------
0181 There is no revert possible, once it is pushed out, it stays like that.
0182 Please send incremental versions on top of what has been merged in order to fix
0183 the patches the way they would look like if your latest patch series was to be
0184 merged.
0185
0186 Are there special rules regarding stable submissions on netdev?
0187 ---------------------------------------------------------------
0188 While it used to be the case that netdev submissions were not supposed
0189 to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
0190 the case today. Please follow the standard stable rules in
0191 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
0192 and make sure you include appropriate Fixes tags!
0193
0194 Is the comment style convention different for the networking content?
0195 ---------------------------------------------------------------------
0196 Yes, in a largely trivial way. Instead of this::
0197
0198 /*
0199 * foobar blah blah blah
0200 * another line of text
0201 */
0202
0203 it is requested that you make it look like this::
0204
0205 /* foobar blah blah blah
0206 * another line of text
0207 */
0208
0209 What is "reverse xmas tree"?
0210 ----------------------------
0211
0212 Netdev has a convention for ordering local variables in functions.
0213 Order the variable declaration lines longest to shortest, e.g.::
0214
0215 struct scatterlist *sg;
0216 struct sk_buff *skb;
0217 int err, i;
0218
0219 If there are dependencies between the variables preventing the ordering
0220 move the initialization out of line.
0221
0222 I am working in existing code which uses non-standard formatting. Which formatting should I use?
0223 ------------------------------------------------------------------------------------------------
0224 Make your code follow the most recent guidelines, so that eventually all code
0225 in the domain of netdev is in the preferred format.
0226
0227 I found a bug that might have possible security implications or similar. Should I mail the main netdev maintainer off-list?
0228 ---------------------------------------------------------------------------------------------------------------------------
0229 No. The current netdev maintainer has consistently requested that
0230 people use the mailing lists and not reach out directly. If you aren't
0231 OK with that, then perhaps consider mailing security@kernel.org or
0232 reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
0233 as possible alternative mechanisms.
0234
0235 What level of testing is expected before I submit my change?
0236 ------------------------------------------------------------
0237 At the very minimum your changes must survive an ``allyesconfig`` and an
0238 ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
0239
0240 Ideally you will have done run-time testing specific to your change,
0241 and the patch series contains a set of kernel selftest for
0242 ``tools/testing/selftests/net`` or using the KUnit framework.
0243
0244 You are expected to test your changes on top of the relevant networking
0245 tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
0246
0247 How do I post corresponding changes to user space components?
0248 -------------------------------------------------------------
0249 User space code exercising kernel features should be posted
0250 alongside kernel patches. This gives reviewers a chance to see
0251 how any new interface is used and how well it works.
0252
0253 When user space tools reside in the kernel repo itself all changes
0254 should generally come as one series. If series becomes too large
0255 or the user space project is not reviewed on netdev include a link
0256 to a public repo where user space patches can be seen.
0257
0258 In case user space tooling lives in a separate repository but is
0259 reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and
0260 user space patches should form separate series (threads) when posted
0261 to the mailing list, e.g.::
0262
0263 [PATCH net-next 0/3] net: some feature cover letter
0264 └─ [PATCH net-next 1/3] net: some feature prep
0265 └─ [PATCH net-next 2/3] net: some feature do it
0266 └─ [PATCH net-next 3/3] selftest: net: some feature
0267
0268 [PATCH iproute2-next] ip: add support for some feature
0269
0270 Posting as one thread is discouraged because it confuses patchwork
0271 (as of patchwork 2.2.2).
0272
0273 Can I reproduce the checks from patchwork on my local machine?
0274 --------------------------------------------------------------
0275
0276 Checks in patchwork are mostly simple wrappers around existing kernel
0277 scripts, the sources are available at:
0278
0279 https://github.com/kuba-moo/nipa/tree/master/tests
0280
0281 Running all the builds and checks locally is a pain, can I post my patches and have the patchwork bot validate them?
0282 --------------------------------------------------------------------------------------------------------------------
0283
0284 No, you must ensure that your patches are ready by testing them locally
0285 before posting to the mailing list. The patchwork build bot instance
0286 gets overloaded very easily and netdev@vger really doesn't need more
0287 traffic if we can help it.
0288
0289 netdevsim is great, can I extend it for my out-of-tree tests?
0290 -------------------------------------------------------------
0291
0292 No, ``netdevsim`` is a test vehicle solely for upstream tests.
0293 (Please add your tests under ``tools/testing/selftests/``.)
0294
0295 We also give no guarantees that ``netdevsim`` won't change in the future
0296 in a way which would break what would normally be considered uAPI.
0297
0298 Is netdevsim considered a "user" of an API?
0299 -------------------------------------------
0300
0301 Linux kernel has a long standing rule that no API should be added unless
0302 it has a real, in-tree user. Mock-ups and tests based on ``netdevsim`` are
0303 strongly encouraged when adding new APIs, but ``netdevsim`` in itself
0304 is **not** considered a use case/user.
0305
0306 Any other tips to help ensure my net/net-next patch gets OK'd?
0307 --------------------------------------------------------------
0308 Attention to detail. Re-read your own work as if you were the
0309 reviewer. You can start with using ``checkpatch.pl``, perhaps even with
0310 the ``--strict`` flag. But do not be mindlessly robotic in doing so.
0311 If your change is a bug fix, make sure your commit log indicates the
0312 end-user visible symptom, the underlying reason as to why it happens,
0313 and then if necessary, explain why the fix proposed is the best way to
0314 get things done. Don't mangle whitespace, and as is common, don't
0315 mis-indent function arguments that span multiple lines. If it is your
0316 first patch, mail it to yourself so you can test apply it to an
0317 unpatched tree to confirm infrastructure didn't mangle it.
0318
0319 Finally, go back and read
0320 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
0321 to be sure you are not repeating some common mistake documented there.
