On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
>
> Signed-off-by: Thorsten Leemhuis <linux@xxxxxxxxxxxxx>
> ---
> Documentation/admin-guide/reporting-bugs.rst | 103 +++++++++++++++++++
> 1 file changed, 103 insertions(+)
>
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 7bde6f32ff72..203df36af55f 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -53,6 +53,109 @@ Security issues are typically best report privately; also CC the security team
> or forward your report there.
>
>
> +Step-by-step guide how to report issues to the kernel maintainers
> +=================================================================
> +
> +Above TL;DR outlines roughly how to report issues to the Linux kernel
The above
> +developers. It might be all that's needed for people already familiar with
> +reporting issues to Free/Libre & Open Source Software (FLOSS) projects. For
> +everyone else there is this section. It is more detailed and uses a
> +step-by-step approach. It still tries to be brief for readability; if it's to
too
> +brief for you, look up the details in the reference section below, where each
> +of the steps is explained in more detail.
> +
> +Note, this section covers a few more aspects than the TL;DR and does things in a
Note:
> +slightly different order. That's in your interest, to make sure you notice early
> +if an issue that looks like a Linux kernel problem is actually caused by
> +something else. These steps thus help to ensure the time you invest in this
> +process won't feel wasted in the end:
> +
> + * Stop reading this document and report the problem to your vendor instead,
> + unless you are running a vanilla mainline kernel already or are willing to
> + install it.
> +
> + * See if the issue you are dealing with qualifies as regression, security
> + issue, or a really severe problem: those are 'issues of high priority' that
> + need special handling in some steps that are about to follow.
> +
> + * Check if your kernel was 'tainted' when the issue occurred, as the event that
> + made the kernel set this flag might be causing the issue you face.
> +
> + * Locate the driver or kernel subsystem that seems to be causing the issue.
> + Find out how and where its developers expect reports. Note: most of the time
> + this won't be `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as issues
> + typically need to be sent by mail to a maintainer and a public mailing list.
> +
> + * Search the archives of the bug tracker or mailing list in question
> + thoroughly for reports that might match your issue. Also check if you find
> + something with your favorite internet search engine or in the `Linux Kernel
> + Mailing List (LKML) archives <https://lore.kernel.org/lkml/>`_. If you find
> + anything, join the discussion instead of sending a new report.
> +
> + * Create a fresh backup and put system repair and restore tools at hand.
> +
> + * Ensure your system does not enhance its kernels by building additional
> + kernel modules on-the-fly locally, which solutions like DKMS might be doing
> + without your knowledge.
> +
> + * Make sure it's not the kernels surroundings that are causing the issue you
kernel's
> + face.
> +
> + * Write down coarsely how to reproduce the issue. If you deal with multiple
> + issue at once, create separate notes for each of them and make sure they
issues
> + work independently on a freshly booted system. That's needed, as each issue
> + needs to get reported to the kernel developers separately, unless they are
> + strongly entangled.
> +
> +After these preparations you'll now enter the main part:
> +
> + * Install the latest Linux mainline kernel: that's where all issue get fixed
> + first, because it's the version line the kernel developers mainly care about.
> + Testing and reporting with the latest Linux stable kernel can be acceptable
can be an acceptable
> + alternative in some situations, but is best avoided.
> +
> + * Ensure the kernel you just installed does not 'taint' itself when running.
> +
> + * Reproduce the issue with the kernel you just installed. If it doesn't show up
> + there, head over to the instructions for issues only happening with stable
> + and longterm kernels if you want to see it fixed there.
Can you link (reference) to that section?
> +
> + * Optimize your notes: try to find and write the most straightforward way to
> + reproduce your issue. Make sure the end result has all the important details,
> + and at the same time is easy to read and understand for others that hear
> + about it for the first time. And if you learned something in this process,
> + consider searching again for existing reports about the issue.
> +
> + * If the failure includes a stack dump, like an Oops does, consider decoding it
> + to find the offending line of code.
Refer to scripts/decodecode ?
or is that done elsewhere?
> +
> + * If your problem is a regression, try to narrow down when the issue was
> + introduced as much as possible.
> +
> + * Start to compile the report by writing a detailed description about the
> + issue. Always mentions a few things: the latest kernel version you installed
> + for reproducing, the Linux Distribution used, and your notes how to
I would say: notes on how to
Maybe it's just me.
> + reproduce the issue. Ideally, make the kernels build configuration (.config)
kernel's
> + and the output from ``dmesg`` available somewhere on the net and link to it.
> + Include or upload all other information that might be relevant, like the
> + output/screenshot of an Oops or the output from ``lspci``. Once you
> + wrote this main part insert a normal length paragraph on top of it outlining
part, insert
> + the issue and the impact quickly. On top of this add one sentence that
> + briefly describes the problem and gets people to read on. Now give the thing
> + a descriptive title or subject that yet again is shorter. Then you're ready
> + to send or file the report like the `MAINTAINERS file
> + <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
> + told you, unless you are dealing with one of those 'issues of high priority':
tells you,
OK, I like present tense as much as possible.
> + they need special care which is explained in 'Special handling for high
> + priority issues' below.
Can we provide a link to that section here?
> +
> + * Wait for reactions and keep the thing rolling until you can accept the
> + outcome in one way or the other. Thus react publicly and in a timely manner
> + to any inquiries. Test proposed fixes. Do proactive testing when a new rc1
when a new -rc
(release candidate) is released. Send
> + gets released. Sent friendly reminders if things stall. And try to help
> + yourself, if you don't get any help or if it is unsatisfying.
> +
> +
> .. ############################################################################
> .. 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
