Re: [RFC PATCH v1 21/26] docs: reporting-bugs: details on writing and sending the report
Many thx for you comments. Consider all the obvious spelling and grammatical mistakes you pointed out fixed, I won't mention all of them in this reply to keep things easier to follow. Am 09.10.20 um 04:45 schrieb Randy Dunlap: On 10/1/20 1:39 AM, Thorsten Leemhuis wrote: + In both cases make sure to inform those that the MAINTAINERS file lists in + the section 'security contact'. Ideally CCing them on the mail with the + report. If you filed it in a bug tracker forward the reports text, but on top parse error in first 2 sentences above... Now reads: In both cases make sure to mail your report to the addresses the MAINTAINERS file lists in the section 'security contact'. Ideally directly CC them when sending the report by mail. Ciao, Thorsten
Re: [RFC PATCH v1 21/26] docs: reporting-bugs: details on writing and sending the report
On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Outline how to write the report. Give instructions that hopefully will
> make people write better reports that ideally are also quick to evaluate
> for kernel developers.
>
> At the same time put some more faith into the readers to make them
> provide all relevant data. That's a bit different to the old approach,
> which told people to always send contents of files like /proc/ioports or
> /proc/iomem, which in a lot of cases won't be needed and make reports
> unnecessarily big.
>
> That's also why this commit removes scripts/ver_linux as well: the
> details it collects are only needed in some situations and make reports
> bigger and harder to compile without good reason. Additionally, some
> distributions do not ship it; a better, more modern script would likely
> resist in tools/, then distros might start shipping it in packages like
> "linux-tools".
>
> Signed-off-by: Thorsten Leemhuis
> ---
> Documentation/admin-guide/reporting-bugs.rst | 247 +++
> scripts/ver_linux| 81 --
> 2 files changed, 198 insertions(+), 130 deletions(-)
> delete mode 100755 scripts/ver_linux
>
> diff --git a/Documentation/admin-guide/reporting-bugs.rst
> b/Documentation/admin-guide/reporting-bugs.rst
> index 71c49347c544..b06935cad880 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -845,6 +845,204 @@ freshly to each newer kernel version you try.
> Afterwards run
> enabling any new feature, as those are allowed to cause regressions.
>
>
> +Write and send the report
> +-
> +
> +*Start to compile the report by writing a detailed description about the
> +issue. Always mentions a few things: the latest kernel version you
> installed
mention
> +for reproducing, the Linux Distribution used, and your notes how to
notes {of,on} how
to
> +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
> 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 told you, unless you
> are
> +dealing with one of those 'issues of high priority': they need special
> care
> +which is explained in 'Special handling for high priority issues' below.*
> +
> +Now that you have prepared everything it's time to write your report. How to
> do
> +that is partly explained by the two documents linked to in the preface above.
> +
> +This text will only mention a few of the essentials as well as things
> apecific
specific
> +to the Linux kernel. There is one thing that fits both categories: the most
> +crucial parts of your report are the title/subject, the first sentence and
> the
> +first paragraph. Developers often get quite a lot of mail and have to quickly
> +decide if one is really worth reading. Developer sometimes take just a few
> +seconds to skim a mail before deciding if it's worth a closer look. Thus: the
> +better the top section of your report, the higher are the chances that
> someone
> +will look into it and help you. And that why you should ignore them for now
that is why
> +and write the detailed report first. ;-)
> +
> +Things each report should mention
> +~
> +
> +Describe in detail how your issue happens with the fresh vanilla kernel you
> +installed. Try to include the step-by-step instructions you wrote and
> optimized
> +earlier that descibe how you and ideally others can reproduce the issue; in
describe
> +those rare cases where that's impossible try to describe what you did to
> trigger
> +it.
> +
> +Also include all the relevant information others might need to understand the
> +issue and its environment. What's actually needed depends a lot on the issue,
> +but there are some things you should include always:
> +
> + * the output from ``cat /proc/version``, which contains the Linux kernel
> + version number and the compiler it was built with.
> +
> + * the Linux distribution the machine is running (``hostnamectl | grep
> + "Operating System"``)
> +
> + * the architecture of the CPU and the operating sy
[RFC PATCH v1 21/26] docs: reporting-bugs: details on writing and sending the report
Outline how to write the report. Give instructions that hopefully will make people write better reports that ideally are also quick to evaluate for kernel developers. At the same time put some more faith into the readers to make them provide all relevant data. That's a bit different to the old approach, which told people to always send contents of files like /proc/ioports or /proc/iomem, which in a lot of cases won't be needed and make reports unnecessarily big. That's also why this commit removes scripts/ver_linux as well: the details it collects are only needed in some situations and make reports bigger and harder to compile without good reason. Additionally, some distributions do not ship it; a better, more modern script would likely resist in tools/, then distros might start shipping it in packages like "linux-tools". Signed-off-by: Thorsten Leemhuis --- Documentation/admin-guide/reporting-bugs.rst | 247 +++ scripts/ver_linux| 81 -- 2 files changed, 198 insertions(+), 130 deletions(-) delete mode 100755 scripts/ver_linux diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst index 71c49347c544..b06935cad880 100644 --- a/Documentation/admin-guide/reporting-bugs.rst +++ b/Documentation/admin-guide/reporting-bugs.rst @@ -845,6 +845,204 @@ freshly to each newer kernel version you try. Afterwards run enabling any new feature, as those are allowed to cause regressions. +Write and send the report +- + +*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 +reproduce the issue. Ideally, make the kernels build configuration (.config) +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 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 told you, unless you are +dealing with one of those 'issues of high priority': they need special care +which is explained in 'Special handling for high priority issues' below.* + +Now that you have prepared everything it's time to write your report. How to do +that is partly explained by the two documents linked to in the preface above. + +This text will only mention a few of the essentials as well as things apecific +to the Linux kernel. There is one thing that fits both categories: the most +crucial parts of your report are the title/subject, the first sentence and the +first paragraph. Developers often get quite a lot of mail and have to quickly +decide if one is really worth reading. Developer sometimes take just a few +seconds to skim a mail before deciding if it's worth a closer look. Thus: the +better the top section of your report, the higher are the chances that someone +will look into it and help you. And that why you should ignore them for now +and write the detailed report first. ;-) + +Things each report should mention +~ + +Describe in detail how your issue happens with the fresh vanilla kernel you +installed. Try to include the step-by-step instructions you wrote and optimized +earlier that descibe how you and ideally others can reproduce the issue; in +those rare cases where that's impossible try to describe what you did to trigger +it. + +Also include all the relevant information others might need to understand the +issue and its environment. What's actually needed depends a lot on the issue, +but there are some things you should include always: + + * the output from ``cat /proc/version``, which contains the Linux kernel + version number and the compiler it was built with. + + * the Linux distribution the machine is running (``hostnamectl | grep + "Operating System"``) + + * the architecture of the CPU and the operating system (``uname -mi``) + + * if you are dealing with a regression and performed a bisection, mention the + subject and the commit-id of the culprit. + +In a lot of cases it's also wise to make two more things available to those +that read your report: + + * the configuration used for building your Linux kernel (the '.config' file) + + * the kernels messages that you get from ``dmesg``. Make sure it near the top + contains a line like 'Linux version 5.8-1 (foo...@example.com) (gcc (GCC) + 10.2.1, GNU ld version 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020', as + otherwise messages fr
