Commit | Line | Data |
---|---|---|
96398ddf TH |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | .. _netdev-FAQ: | |
4 | ||
5 | ========== | |
6 | netdev FAQ | |
7 | ========== | |
8 | ||
1d898b28 BS |
9 | What is netdev? |
10 | --------------- | |
11 | It is a mailing list for all network-related Linux stuff. This | |
96398ddf TH |
12 | includes anything found under net/ (i.e. core code like IPv6) and |
13 | drivers/net (i.e. hardware specific drivers) in the Linux source tree. | |
14 | ||
15 | Note that some subsystems (e.g. wireless drivers) which have a high | |
16 | volume of traffic have their own specific mailing lists. | |
17 | ||
18 | The netdev list is managed (like many other Linux mailing lists) through | |
19 | VGER (http://vger.kernel.org/) and archives can be found below: | |
20 | ||
21 | - http://marc.info/?l=linux-netdev | |
22 | - http://www.spinics.net/lists/netdev/ | |
23 | ||
24 | Aside from subsystems like that mentioned above, all network-related | |
25 | Linux development (i.e. RFC, review, comments, etc.) takes place on | |
26 | netdev. | |
27 | ||
1d898b28 BS |
28 | How do the changes posted to netdev make their way into Linux? |
29 | -------------------------------------------------------------- | |
30 | There are always two trees (git repositories) in play. Both are | |
96398ddf TH |
31 | driven by David Miller, the main network maintainer. There is the |
32 | ``net`` tree, and the ``net-next`` tree. As you can probably guess from | |
33 | the names, the ``net`` tree is for fixes to existing code already in the | |
34 | mainline tree from Linus, and ``net-next`` is where the new code goes | |
35 | for the future release. You can find the trees here: | |
36 | ||
e64b274c JDB |
37 | - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git |
38 | - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git | |
96398ddf | 39 | |
1d898b28 BS |
40 | How often do changes from these trees make it to the mainline Linus tree? |
41 | ------------------------------------------------------------------------- | |
42 | To understand this, you need to know a bit of background information on | |
96398ddf TH |
43 | the cadence of Linux development. Each new release starts off with a |
44 | two week "merge window" where the main maintainers feed their new stuff | |
45 | to Linus for merging into the mainline tree. After the two weeks, the | |
46 | merge window is closed, and it is called/tagged ``-rc1``. No new | |
47 | features get mainlined after this -- only fixes to the rc1 content are | |
48 | expected. After roughly a week of collecting fixes to the rc1 content, | |
49 | rc2 is released. This repeats on a roughly weekly basis until rc7 | |
50 | (typically; sometimes rc6 if things are quiet, or rc8 if things are in a | |
51 | state of churn), and a week after the last vX.Y-rcN was done, the | |
52 | official vX.Y is released. | |
53 | ||
54 | Relating that to netdev: At the beginning of the 2-week merge window, | |
55 | the ``net-next`` tree will be closed - no new changes/features. The | |
56 | accumulated new content of the past ~10 weeks will be passed onto | |
57 | mainline/Linus via a pull request for vX.Y -- at the same time, the | |
58 | ``net`` tree will start accumulating fixes for this pulled content | |
59 | relating to vX.Y | |
60 | ||
61 | An announcement indicating when ``net-next`` has been closed is usually | |
62 | sent to netdev, but knowing the above, you can predict that in advance. | |
63 | ||
64 | IMPORTANT: Do not send new ``net-next`` content to netdev during the | |
65 | period during which ``net-next`` tree is closed. | |
66 | ||
67 | Shortly after the two weeks have passed (and vX.Y-rc1 is released), the | |
68 | tree for ``net-next`` reopens to collect content for the next (vX.Y+1) | |
69 | release. | |
70 | ||
71 | If you aren't subscribed to netdev and/or are simply unsure if | |
72 | ``net-next`` has re-opened yet, simply check the ``net-next`` git | |
73 | repository link above for any new networking-related commits. You may | |
74 | also check the following website for the current status: | |
75 | ||
76 | http://vger.kernel.org/~davem/net-next.html | |
77 | ||
78 | The ``net`` tree continues to collect fixes for the vX.Y content, and is | |
79 | fed back to Linus at regular (~weekly) intervals. Meaning that the | |
80 | focus for ``net`` is on stabilization and bug fixes. | |
81 | ||
82 | Finally, the vX.Y gets released, and the whole cycle starts over. | |
83 | ||
1d898b28 BS |
84 | So where are we now in this cycle? |
85 | ---------------------------------- | |
96398ddf TH |
86 | |
87 | Load the mainline (Linus) page here: | |
88 | ||
89 | https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git | |
90 | ||
91 | and note the top of the "tags" section. If it is rc1, it is early in | |
92 | the dev cycle. If it was tagged rc7 a week ago, then a release is | |
93 | probably imminent. | |
94 | ||
1d898b28 BS |
95 | How do I indicate which tree (net vs. net-next) my patch should be in? |
96 | ---------------------------------------------------------------------- | |
97 | Firstly, think whether you have a bug fix or new "next-like" content. | |
96398ddf TH |
98 | Then once decided, assuming that you use git, use the prefix flag, i.e. |
99 | :: | |
100 | ||
101 | git format-patch --subject-prefix='PATCH net-next' start..finish | |
102 | ||
103 | Use ``net`` instead of ``net-next`` (always lower case) in the above for | |
104 | bug-fix ``net`` content. If you don't use git, then note the only magic | |
105 | in the above is just the subject text of the outgoing e-mail, and you | |
106 | can manually change it yourself with whatever MUA you are comfortable | |
107 | with. | |
108 | ||
1d898b28 BS |
109 | I sent a patch and I'm wondering what happened to it - how can I tell whether it got merged? |
110 | -------------------------------------------------------------------------------------------- | |
111 | Start by looking at the main patchworks queue for netdev: | |
96398ddf | 112 | |
460cd17e | 113 | https://patchwork.kernel.org/project/netdevbpf/list/ |
96398ddf TH |
114 | |
115 | The "State" field will tell you exactly where things are at with your | |
116 | patch. | |
117 | ||
1d898b28 BS |
118 | The above only says "Under Review". How can I find out more? |
119 | ------------------------------------------------------------- | |
120 | Generally speaking, the patches get triaged quickly (in less than | |
96398ddf TH |
121 | 48h). So be patient. Asking the maintainer for status updates on your |
122 | patch is a good way to ensure your patch is ignored or pushed to the | |
123 | bottom of the priority list. | |
124 | ||
1d898b28 BS |
125 | I submitted multiple versions of the patch series. Should I directly update patchwork for the previous versions of these patch series? |
126 | -------------------------------------------------------------------------------------------------------------------------------------- | |
127 | No, please don't interfere with the patch status on patchwork, leave | |
96398ddf TH |
128 | it to the maintainer to figure out what is the most recent and current |
129 | version that should be applied. If there is any doubt, the maintainer | |
130 | will reply and ask what should be done. | |
131 | ||
1d898b28 BS |
132 | I made changes to only a few patches in a patch series should I resend only those changed? |
133 | ------------------------------------------------------------------------------------------ | |
134 | No, please resend the entire patch series and make sure you do number your | |
ffa91253 FF |
135 | patches such that it is clear this is the latest and greatest set of patches |
136 | that can be applied. | |
137 | ||
1d898b28 BS |
138 | 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? |
139 | ---------------------------------------------------------------------------------------------------------------------------------------- | |
140 | There is no revert possible, once it is pushed out, it stays like that. | |
ffa91253 FF |
141 | Please send incremental versions on top of what has been merged in order to fix |
142 | the patches the way they would look like if your latest patch series was to be | |
143 | merged. | |
144 | ||
dbbe7c96 | 145 | Are there special rules regarding stable submissions on netdev? |
1d898b28 | 146 | --------------------------------------------------------------- |
dbbe7c96 JK |
147 | While it used to be the case that netdev submissions were not supposed |
148 | to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer | |
149 | the case today. Please follow the standard stable rules in | |
150 | :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`, | |
151 | and make sure you include appropriate Fixes tags! | |
96398ddf | 152 | |
1d898b28 BS |
153 | Is the comment style convention different for the networking content? |
154 | --------------------------------------------------------------------- | |
155 | Yes, in a largely trivial way. Instead of this:: | |
96398ddf TH |
156 | |
157 | /* | |
158 | * foobar blah blah blah | |
159 | * another line of text | |
160 | */ | |
161 | ||
162 | it is requested that you make it look like this:: | |
163 | ||
164 | /* foobar blah blah blah | |
165 | * another line of text | |
166 | */ | |
167 | ||
1d898b28 BS |
168 | I am working in existing code that has the former comment style and not the latter. Should I submit new code in the former style or the latter? |
169 | ----------------------------------------------------------------------------------------------------------------------------------------------- | |
170 | Make it the latter style, so that eventually all code in the domain | |
96398ddf TH |
171 | of netdev is of this format. |
172 | ||
1d898b28 BS |
173 | I found a bug that might have possible security implications or similar. Should I mail the main netdev maintainer off-list? |
174 | --------------------------------------------------------------------------------------------------------------------------- | |
175 | No. The current netdev maintainer has consistently requested that | |
96398ddf TH |
176 | people use the mailing lists and not reach out directly. If you aren't |
177 | OK with that, then perhaps consider mailing security@kernel.org or | |
178 | reading about http://oss-security.openwall.org/wiki/mailing-lists/distros | |
179 | as possible alternative mechanisms. | |
180 | ||
1d898b28 BS |
181 | What level of testing is expected before I submit my change? |
182 | ------------------------------------------------------------ | |
183 | If your changes are against ``net-next``, the expectation is that you | |
96398ddf TH |
184 | have tested by layering your changes on top of ``net-next``. Ideally |
185 | you will have done run-time testing specific to your change, but at a | |
186 | minimum, your changes should survive an ``allyesconfig`` and an | |
187 | ``allmodconfig`` build without new warnings or failures. | |
188 | ||
1d898b28 BS |
189 | How do I post corresponding changes to user space components? |
190 | ------------------------------------------------------------- | |
191 | User space code exercising kernel features should be posted | |
6f7a1f9c JK |
192 | alongside kernel patches. This gives reviewers a chance to see |
193 | how any new interface is used and how well it works. | |
194 | ||
195 | When user space tools reside in the kernel repo itself all changes | |
196 | should generally come as one series. If series becomes too large | |
197 | or the user space project is not reviewed on netdev include a link | |
198 | to a public repo where user space patches can be seen. | |
199 | ||
200 | In case user space tooling lives in a separate repository but is | |
201 | reviewed on netdev (e.g. patches to `iproute2` tools) kernel and | |
202 | user space patches should form separate series (threads) when posted | |
203 | to the mailing list, e.g.:: | |
204 | ||
205 | [PATCH net-next 0/3] net: some feature cover letter | |
206 | └─ [PATCH net-next 1/3] net: some feature prep | |
207 | └─ [PATCH net-next 2/3] net: some feature do it | |
208 | └─ [PATCH net-next 3/3] selftest: net: some feature | |
209 | ||
210 | [PATCH iproute2-next] ip: add support for some feature | |
211 | ||
212 | Posting as one thread is discouraged because it confuses patchwork | |
213 | (as of patchwork 2.2.2). | |
214 | ||
f1d77b2e JK |
215 | Can I reproduce the checks from patchwork on my local machine? |
216 | -------------------------------------------------------------- | |
217 | ||
218 | Checks in patchwork are mostly simple wrappers around existing kernel | |
219 | scripts, the sources are available at: | |
220 | ||
221 | https://github.com/kuba-moo/nipa/tree/master/tests | |
222 | ||
223 | Running all the builds and checks locally is a pain, can I post my patches and have the patchwork bot validate them? | |
224 | -------------------------------------------------------------------------------------------------------------------- | |
225 | ||
226 | No, you must ensure that your patches are ready by testing them locally | |
227 | before posting to the mailing list. The patchwork build bot instance | |
228 | gets overloaded very easily and netdev@vger really doesn't need more | |
229 | traffic if we can help it. | |
230 | ||
396492b4 JK |
231 | netdevsim is great, can I extend it for my out-of-tree tests? |
232 | ------------------------------------------------------------- | |
233 | ||
234 | No, `netdevsim` is a test vehicle solely for upstream tests. | |
235 | (Please add your tests under tools/testing/selftests/.) | |
236 | ||
237 | We also give no guarantees that `netdevsim` won't change in the future | |
238 | in a way which would break what would normally be considered uAPI. | |
239 | ||
240 | Is netdevsim considered a "user" of an API? | |
241 | ------------------------------------------- | |
242 | ||
243 | Linux kernel has a long standing rule that no API should be added unless | |
244 | it has a real, in-tree user. Mock-ups and tests based on `netdevsim` are | |
245 | strongly encouraged when adding new APIs, but `netdevsim` in itself | |
246 | is **not** considered a use case/user. | |
247 | ||
1d898b28 BS |
248 | Any other tips to help ensure my net/net-next patch gets OK'd? |
249 | -------------------------------------------------------------- | |
250 | Attention to detail. Re-read your own work as if you were the | |
96398ddf TH |
251 | reviewer. You can start with using ``checkpatch.pl``, perhaps even with |
252 | the ``--strict`` flag. But do not be mindlessly robotic in doing so. | |
253 | If your change is a bug fix, make sure your commit log indicates the | |
254 | end-user visible symptom, the underlying reason as to why it happens, | |
255 | and then if necessary, explain why the fix proposed is the best way to | |
256 | get things done. Don't mangle whitespace, and as is common, don't | |
257 | mis-indent function arguments that span multiple lines. If it is your | |
258 | first patch, mail it to yourself so you can test apply it to an | |
259 | unpatched tree to confirm infrastructure didn't mangle it. | |
260 | ||
261 | Finally, go back and read | |
262 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` | |
263 | to be sure you are not repeating some common mistake documented there. |