docs: reporting-issues: tweak the reference section intro

+26 -31

1 changed file

expand all

Documentation

admin-guide

+26 -31

Documentation/admin-guide/reporting-issues.rst

··· 244 244 Reference section: Reporting issues to the kernel maintainers 245 245 ============================================================= 246 246 247 - The detailed guides above outline all the major steps in brief fashion, which 248 - should be enough for most people. But sometimes there are situations where even 249 - experienced users might wonder how to actually do one of those steps. That's 250 - what this section is for, as it will provide a lot more details on each of the 251 - above steps. Consider this as reference documentation: it's possible to read it 252 - from top to bottom. But it's mainly meant to skim over and a place to look up 253 - details how to actually perform those steps. 247 + The step-by-step guide above outlines all the major steps in brief fashion, 248 + which usually covers everything required. But even experienced users will 249 + sometimes wonder how to actually realize some of those steps or why they are 250 + needed; there are also corner cases the guide ignores for readability. That is 251 + what the entries in this reference section are for, which provide additional 252 + information for each of the steps in the guide. 254 253 255 - A few words of general advice before digging into the details: 254 + A few words of general advice: 256 255 257 - * The Linux kernel developers are well aware this process is complicated and 258 - demands more than other FLOSS projects. We'd love to make it simpler. But 259 - that would require work in various places as well as some infrastructure, 260 - which would need constant maintenance; nobody has stepped up to do that 261 - work, so that's just how things are for now. 256 + * The Linux developers are well aware that reporting bugs to them is more 257 + complicated and demanding than in other FLOSS projects. Some of it is because 258 + the kernel is different, among others due to its mail-driven development 259 + process and because it consists mostly of drivers. Some of it is because 260 + improving things would require work in several technical areas and people 261 + triaging bugs –– and nobody has stepped up to do or fund that work. 262 262 263 - * A warranty or support contract with some vendor doesn't entitle you to 264 - request fixes from developers in the upstream Linux kernel community: such 265 - contracts are completely outside the scope of the Linux kernel, its 266 - development community, and this document. That's why you can't demand 267 - anything such a contract guarantees in this context, not even if the 268 - developer handling the issue works for the vendor in question. If you want 269 - to claim your rights, use the vendor's support channel instead. When doing 270 - so, you might want to mention you'd like to see the issue fixed in the 271 - upstream Linux kernel; motivate them by saying it's the only way to ensure 272 - the fix in the end will get incorporated in all Linux distributions. 263 + * A warranty or support contract with some vendor doesn't entitle you to 264 + request fixes from the upstream Linux developers: Such contracts are 265 + completely outside the scope of the upstream Linux kernel, its development 266 + community, and this document -- even if those handling the issue work for the 267 + vendor who issued the contract. If you want to claim your rights, use the 268 + vendor's support channel. 273 269 274 - * If you never reported an issue to a FLOSS project before you should consider 275 - reading `How to Report Bugs Effectively 276 - <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_, `How To Ask 277 - Questions The Smart Way 278 - <http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to ask good 279 - questions <https://jvns.ca/blog/good-questions/>`_. 270 + * If you never reported an issue to a FLOSS project before, consider skimming 271 + guides like `How to ask good questions 272 + <https://jvns.ca/blog/good-questions/>`_, `How To Ask Questions The Smart Way 273 + <http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to Report 274 + Bugs Effectively <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_,. 280 275 281 - With that off the table, find below the details on how to properly report 282 - issues to the Linux kernel developers. 276 + With that off the table, find below details for the steps from the detailed 277 + guide on reporting issues to the Linux kernel developers. 283 278 284 279 285 280 Make sure you're using the upstream Linux kernel

Configure Feed

Configure Feed