On 10/1/20 1:39 AM, Thorsten Leemhuis wrote: > Get straight to the point in a few paragraphs instead of forcing users > to read quite a bit of text, like the old approach did. > > All normally needed fits into the first two paragraphs. The third is > dedicated to issues only happening in stable and longterm kernels, as > things otherwise get hard to follow. At the end explicitly spell out > that some issues need to be handled slightly different. > > This TLDR naturally leaves lots of details out. But it will be good > enough in some situations, for example for users that recently reported > an issue or are familiar with reporting issues to FLOSS projects. > > Signed-off-by: Thorsten Leemhuis <linux@xxxxxxxxxxxxx> > --- > Documentation/admin-guide/reporting-bugs.rst | 43 ++++++++++++++++++++ > 1 file changed, 43 insertions(+) > > diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst > index 4bbb9132782b..7bde6f32ff72 100644 > --- a/Documentation/admin-guide/reporting-bugs.rst > +++ b/Documentation/admin-guide/reporting-bugs.rst > @@ -10,6 +10,49 @@ Reporting bugs > .. inconsistent/not make sense before all patches of the rewrite got applied. > .. ########################################################################### > > + > +The short guide (aka TL;DR) > +=========================== > + > +This is how you report issues with the Linux kernel to its developers: > + > +If you deal with multiple issues at once, process each of them separately. Try > +your best guess which area of the kernel might be responsible for your issue. > +Check the `MAINTAINERS file > +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_ > +how developers of that particular area expect to be told about issues; note, for how ? > +it's rarely `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as most > +subsystems expect reports by mail sent to their maintainers and their public > +mailing list! > + > +Check the archives of the determined destination thoroughly for existing > +reports; also search the LKML archives and the internet as a whole. If you can't > +find any, install the `latest Linux mainline version <https://kernel.org/>`_. > +Make sure to use a vanilla kernel and avert any add-on kernel modules externally > +developed; also ensure the kernel is running in a healthy environment and does > +not 'taint' itself before the issue occurs. If you can reproduce it, write a I don't care for "does not 'taint' itself". How about and is not already tainted before the issue occurs. > +report to the destination you determined earlier. Afterwards keep the ball > +rolling by proactive testing, a status update now and then, and helping where > +you can. > + > +You can't reproduce an issue with mainline you want to see fixed in older > +version lines? Then make sure the line you care about still gets support. > +Install its latest release as vanilla kernel. If you can reproduce the issue Is "vanilla" well understood? > +there, try to find the commit that fixed it in mainline or any discussion > +preceding it: those will often mention if backporting is planed or impossible; > +if not, ask for it. In case you don't find anything, check if it's a regression > +specific to the version line that need to be bisected and report just like a that needs > +problem in mainline with the stable mailing list CCed. If you reached this point > +without a solution, ask for advice by mailing the subsystem maintainer with the > +subsystem and stable mailing list in CC. > + > +If you deal with a regression, bisect it to find the culprit and CC or forward > +your report to its developers. > + > +Security issues are typically best report privately; also CC the security team reported > +or forward your report there. > + > + > .. ############################################################################ > .. Temporary marker added while this document is rewritten. Sections above > .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old. > -- ~Randy
