Commit | Line | Data |
---|---|---|
96398ddf TH |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | .. _netdev-FAQ: | |
4 | ||
5 | ========== | |
6 | netdev FAQ | |
7 | ========== | |
8 | ||
9 | Q: What is netdev? | |
10 | ------------------ | |
11 | A: It is a mailing list for all network-related Linux stuff. This | |
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 | ||
28 | Q: How do the changes posted to netdev make their way into Linux? | |
29 | ----------------------------------------------------------------- | |
30 | A: There are always two trees (git repositories) in play. Both are | |
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 TH |
39 | |
40 | Q: How often do changes from these trees make it to the mainline Linus tree? | |
41 | ---------------------------------------------------------------------------- | |
42 | A: To understand this, you need to know a bit of background information on | |
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 | ||
84 | Q: So where are we now in this cycle? | |
85 | ||
86 | Load the mainline (Linus) page here: | |
87 | ||
88 | https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git | |
89 | ||
90 | and note the top of the "tags" section. If it is rc1, it is early in | |
91 | the dev cycle. If it was tagged rc7 a week ago, then a release is | |
92 | probably imminent. | |
93 | ||
94 | Q: How do I indicate which tree (net vs. net-next) my patch should be in? | |
95 | ------------------------------------------------------------------------- | |
96 | A: Firstly, think whether you have a bug fix or new "next-like" content. | |
97 | Then once decided, assuming that you use git, use the prefix flag, i.e. | |
98 | :: | |
99 | ||
100 | git format-patch --subject-prefix='PATCH net-next' start..finish | |
101 | ||
102 | Use ``net`` instead of ``net-next`` (always lower case) in the above for | |
103 | bug-fix ``net`` content. If you don't use git, then note the only magic | |
104 | in the above is just the subject text of the outgoing e-mail, and you | |
105 | can manually change it yourself with whatever MUA you are comfortable | |
106 | with. | |
107 | ||
108 | Q: I sent a patch and I'm wondering what happened to it? | |
109 | -------------------------------------------------------- | |
110 | Q: How can I tell whether it got merged? | |
111 | A: Start by looking at the main patchworks queue for netdev: | |
112 | ||
113 | http://patchwork.ozlabs.org/project/netdev/list/ | |
114 | ||
115 | The "State" field will tell you exactly where things are at with your | |
116 | patch. | |
117 | ||
118 | Q: The above only says "Under Review". How can I find out more? | |
119 | ---------------------------------------------------------------- | |
120 | A: Generally speaking, the patches get triaged quickly (in less than | |
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 | ||
125 | Q: I submitted multiple versions of the patch series | |
126 | ---------------------------------------------------- | |
127 | Q: should I directly update patchwork for the previous versions of these | |
128 | patch series? | |
129 | A: No, please don't interfere with the patch status on patchwork, leave | |
130 | it to the maintainer to figure out what is the most recent and current | |
131 | version that should be applied. If there is any doubt, the maintainer | |
132 | will reply and ask what should be done. | |
133 | ||
ffa91253 | 134 | Q: I made changes to only a few patches in a patch series should I resend only those changed? |
799381e4 | 135 | --------------------------------------------------------------------------------------------- |
ffa91253 FF |
136 | A: No, please resend the entire patch series and make sure you do number your |
137 | patches such that it is clear this is the latest and greatest set of patches | |
138 | that can be applied. | |
139 | ||
140 | Q: 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? | |
141 | ------------------------------------------------------------------------------------------------------------------------------------------- | |
142 | A: There is no revert possible, once it is pushed out, it stays like that. | |
143 | Please send incremental versions on top of what has been merged in order to fix | |
144 | the patches the way they would look like if your latest patch series was to be | |
145 | merged. | |
146 | ||
96398ddf TH |
147 | Q: How can I tell what patches are queued up for backporting to the various stable releases? |
148 | -------------------------------------------------------------------------------------------- | |
149 | A: Normally Greg Kroah-Hartman collects stable commits himself, but for | |
150 | networking, Dave collects up patches he deems critical for the | |
151 | networking subsystem, and then hands them off to Greg. | |
152 | ||
153 | There is a patchworks queue that you can see here: | |
154 | ||
155 | http://patchwork.ozlabs.org/bundle/davem/stable/?state=* | |
156 | ||
157 | It contains the patches which Dave has selected, but not yet handed off | |
158 | to Greg. If Greg already has the patch, then it will be here: | |
159 | ||
160 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git | |
161 | ||
162 | A quick way to find whether the patch is in this stable-queue is to | |
163 | simply clone the repo, and then git grep the mainline commit ID, e.g. | |
164 | :: | |
165 | ||
166 | stable-queue$ git grep -l 284041ef21fdf2e | |
167 | releases/3.0.84/ipv6-fix-possible-crashes-in-ip6_cork_release.patch | |
168 | releases/3.4.51/ipv6-fix-possible-crashes-in-ip6_cork_release.patch | |
169 | releases/3.9.8/ipv6-fix-possible-crashes-in-ip6_cork_release.patch | |
170 | stable/stable-queue$ | |
171 | ||
172 | Q: I see a network patch and I think it should be backported to stable. | |
173 | ----------------------------------------------------------------------- | |
174 | Q: Should I request it via stable@vger.kernel.org like the references in | |
175 | the kernel's Documentation/process/stable-kernel-rules.rst file say? | |
176 | A: No, not for networking. Check the stable queues as per above first | |
177 | to see if it is already queued. If not, then send a mail to netdev, | |
178 | listing the upstream commit ID and why you think it should be a stable | |
179 | candidate. | |
180 | ||
181 | Before you jump to go do the above, do note that the normal stable rules | |
182 | in :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` | |
183 | still apply. So you need to explicitly indicate why it is a critical | |
184 | fix and exactly what users are impacted. In addition, you need to | |
185 | convince yourself that you *really* think it has been overlooked, | |
186 | vs. having been considered and rejected. | |
187 | ||
188 | Generally speaking, the longer it has had a chance to "soak" in | |
189 | mainline, the better the odds that it is an OK candidate for stable. So | |
190 | scrambling to request a commit be added the day after it appears should | |
191 | be avoided. | |
192 | ||
193 | Q: I have created a network patch and I think it should be backported to stable. | |
194 | -------------------------------------------------------------------------------- | |
195 | Q: Should I add a Cc: stable@vger.kernel.org like the references in the | |
196 | kernel's Documentation/ directory say? | |
197 | A: No. See above answer. In short, if you think it really belongs in | |
198 | stable, then ensure you write a decent commit log that describes who | |
199 | gets impacted by the bug fix and how it manifests itself, and when the | |
200 | bug was introduced. If you do that properly, then the commit will get | |
201 | handled appropriately and most likely get put in the patchworks stable | |
202 | queue if it really warrants it. | |
203 | ||
204 | If you think there is some valid information relating to it being in | |
205 | stable that does *not* belong in the commit log, then use the three dash | |
206 | marker line as described in | |
207 | :ref:`Documentation/process/submitting-patches.rst <the_canonical_patch_format>` | |
208 | to temporarily embed that information into the patch that you send. | |
209 | ||
210 | Q: Are all networking bug fixes backported to all stable releases? | |
211 | ------------------------------------------------------------------ | |
212 | A: Due to capacity, Dave could only take care of the backports for the | |
213 | last two stable releases. For earlier stable releases, each stable | |
214 | branch maintainer is supposed to take care of them. If you find any | |
215 | patch is missing from an earlier stable branch, please notify | |
216 | stable@vger.kernel.org with either a commit ID or a formal patch | |
217 | backported, and CC Dave and other relevant networking developers. | |
218 | ||
219 | Q: Is the comment style convention different for the networking content? | |
220 | ------------------------------------------------------------------------ | |
221 | A: Yes, in a largely trivial way. Instead of this:: | |
222 | ||
223 | /* | |
224 | * foobar blah blah blah | |
225 | * another line of text | |
226 | */ | |
227 | ||
228 | it is requested that you make it look like this:: | |
229 | ||
230 | /* foobar blah blah blah | |
231 | * another line of text | |
232 | */ | |
233 | ||
234 | Q: I am working in existing code that has the former comment style and not the latter. | |
235 | -------------------------------------------------------------------------------------- | |
236 | Q: Should I submit new code in the former style or the latter? | |
237 | A: Make it the latter style, so that eventually all code in the domain | |
238 | of netdev is of this format. | |
239 | ||
240 | Q: I found a bug that might have possible security implications or similar. | |
241 | --------------------------------------------------------------------------- | |
242 | Q: Should I mail the main netdev maintainer off-list?** | |
243 | A: No. The current netdev maintainer has consistently requested that | |
244 | people use the mailing lists and not reach out directly. If you aren't | |
245 | OK with that, then perhaps consider mailing security@kernel.org or | |
246 | reading about http://oss-security.openwall.org/wiki/mailing-lists/distros | |
247 | as possible alternative mechanisms. | |
248 | ||
249 | Q: What level of testing is expected before I submit my change? | |
250 | --------------------------------------------------------------- | |
251 | A: If your changes are against ``net-next``, the expectation is that you | |
252 | have tested by layering your changes on top of ``net-next``. Ideally | |
253 | you will have done run-time testing specific to your change, but at a | |
254 | minimum, your changes should survive an ``allyesconfig`` and an | |
255 | ``allmodconfig`` build without new warnings or failures. | |
256 | ||
257 | Q: Any other tips to help ensure my net/net-next patch gets OK'd? | |
258 | ----------------------------------------------------------------- | |
259 | A: Attention to detail. Re-read your own work as if you were the | |
260 | reviewer. You can start with using ``checkpatch.pl``, perhaps even with | |
261 | the ``--strict`` flag. But do not be mindlessly robotic in doing so. | |
262 | If your change is a bug fix, make sure your commit log indicates the | |
263 | end-user visible symptom, the underlying reason as to why it happens, | |
264 | and then if necessary, explain why the fix proposed is the best way to | |
265 | get things done. Don't mangle whitespace, and as is common, don't | |
266 | mis-indent function arguments that span multiple lines. If it is your | |
267 | first patch, mail it to yourself so you can test apply it to an | |
268 | unpatched tree to confirm infrastructure didn't mangle it. | |
269 | ||
270 | Finally, go back and read | |
271 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` | |
272 | to be sure you are not repeating some common mistake documented there. |