On Wed, Jul 13, 2022 at 11:41 AM Thorsten Leemhuis <linux@xxxxxxxxxxxxx> wrote: > > Hi! Lukas, thx for bringing this up. > > On 13.07.22 09:26, Lukas Bulwahn wrote: > > > > During some other unrelated clean-up work, I stumbled upon the section > > 'If something goes wrong' in Documentation/admin-guide/README.rst > > (https://www.kernel.org/doc/html/latest/admin-guide/README.html). > > README.rst is---as it seems---the intended first summary page of the > > documentation for any user of the kernel (the kernel's release notes > > document). > > > > The section 'If something goes wrong' describes what to do when > > encountering a bug and how to report it. The second sentence in that > > section is especially historic and probably just discouraging for most > > bug reporters ( ..."the second best thing is to mail them to me > > (torvalds@xxxxxxxxxxxxxxxxxxxx)"...). > > Ha, yeah, guess so :-D > > > Some random user (potentially > > even unknown to the community) sending an email to Linus is most > > probably the last best thing to do and is most likely just ignored, > > right? > > I'd say it depends on the report and would guess Linus in quite a few > cases will act on it if the report at least somewhat good -- or about > something important, like a bisected regression. > > > Probably this section in README.rst needs a rewrite (summarizing > > Thorsten's reporting-issues.rst, or just copying the summary from > > there) and should then refer to reporting-issues.rst for more details. > > Well, any new summary sounds a bit like 'similar code paths for doing > the same thing'. Sometimes that is necessary when coding, but often it's > best avoided for known reasons. I think it's not that different for docs. > > Maybe just copying the "short guide" from the top of > reporting-issues.rst might be the most elegant solution for README.rst > while adding the link your mentioned (maybe while adding a comment to > reporting-issues.rst saying something like 'if you update this section, > update the copy over there, too'). But I'm not sure myself right now if > that's really the best way forward; maybe a few modifications might be > good here. Let's see what Jonathan says. > > Note, the section in README.rst you mentioned also contains a few > aspects that reporting-issues.rst despite it's size doesn't cover. :-/ > But some of that stuff looks outdated anyway. > > > Thorsten, do you have time to prepare a change to that document that > > gives a short summary on how to report potential issues and > > regressions? Otherwise, I will happily put that on my todo list and > > probably can suggest some RFC patch in a week or two. > > Then go for it. Normally I'd be interested, but I'm short on time > currently, as I'm working a lot on bugzilla integration for regzbot, > have a vacation coming up, and need to prepare talks for two conferences > (Kernel Summit and Open Source Summit). > Then, I will take the points you mentioned as guidance and prepare a RFC patch and we can discuss what specific changes are needed beyond my first attempt. Lukas
