Re: [RFC PATCH v1 21/26] docs: reporting-bugs: details on writing and sending the report

[Randy Dunlap]

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 <linux@xxxxxxxxxxxxx>
> ---
>  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 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

          kernel's                                      Make sure that it contains
a line lie ' ... ' near the top; otherwise messages


> +   contains a line like 'Linux version 5.8-1 (foobar@xxxxxxxxxxx) (gcc (GCC)
> +   10.2.1, GNU ld version 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020', as
> +   otherwise messages from the first boot phase are already gone from the
> +   buffer. In this case instead consider using ``journalctl -b 0 -k``;
> +   alternatively you can also reboot, reproduce the issue and call ``dmesg``
> +   right afterwards.
> +
> +This data files are big, that's why it's a bad idea to put them directly into

   This data file is big; that's why

> +your report. If you are filing the issue in a bug tracker then attach them to
> +the ticket. If you report the issue by mail do not attach them, as that makes
> +the mail too large; instead do one of these things:
> +
> + * Upload the files somewhere public (your website, a public file paste
> +   service, a ticket created just for this purpose on `bugzilla.kernel.org
> +   <https://bugzilla.kernel.org/>`_, ...) and include a link to them in your
> +   report. Ideally use something where the files stay available for years, as
> +   they could be useful to someone many years from now; this for example can
> +   happen if somebody else runs into the same issue or when a developer works on
> +   some code that was changed to fix your issue.
> +
> + * Put the files aside and mention you will send them later in individual
> +   replies to your own mail. Just remember to actually do that once the report
> +   went out. ;-)
> +
> +Things that might be wise to provide
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Depending on the issue you might need to add more files with background data.
> +Here are a few suggestions what often is good to provide:
> +
> + * If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the kernel,
> +   include it. If you can't copy' n'paste it try to capture a netconsole trace

                  If you can't copy'n'paste it, try

> +   or take a picture of the screen.
> +
> + * If the issue might be related to your computer hardware mention what kind of

                                                     hardware, mention

> +   system you use. If you for example have problems with your graphics card

                                                                          card,

> +   mention its manufacturer and the cards model. If it's a Laptop mention its

                                       card's                 laptop,


> +   name, but try to make sure it's meaningful. 'Dell XPS 13' for example is
> +   not, because it might be the one from 2012; that one might look a bit similar
> +   to the one sold today, but apart from that the two have nothing in common.
> +   Hence, in such cases add the exact model number, which for example are
> +   '9380' or '7390' for XPS 13 models introduced during 2019. Names like
> +   'Lenovo Thinkpad T590' are also somewhat ambiguous: there are variants of
> +   this Laptop with and without a dedicated graphics chip, so try to find the

           laptop

> +   exact models name or specify the main components.

            model's
or          model name

> +
> + * Mention the Software in the environment that's relevant. If you have
> +   problems with loading modules, you want to mention the versions of kmod,
> +   systemd, and udev in use. If one of the DRM drivers misbehaves, you want to
> +   state the versions of libdrm and Mesa; also specify your Wayland compositor
> +   or the X-Server and its driver. If you have a filesystem issue, mention the

             X Server

> +   version of corresponding filesystem utilities (e2fsprogs, btrfs-progs,
> +   xfsprogs, …).

Can we try to use ASCII as much as possible (for text/console readability)?
So just "...".

> +
> + * Gather additional information from the kernel that might be of interest. The
> +   output from ``lspci -nn`` will for example help others to identify what
> +   hardware you use. If you have a problem with hardware you even might want to
> +   make the output from ``sudo lspci -vvv`` available, as that provides
> +   insights how the components were configured. For some issues it might be
> +   good to include the contents of files like ``/proc/cpuinfo``,
> +   ``/proc/ioports``, ``/proc/iomem``, ``/proc/modules``, or
> +   ``/proc/scsi/scsi``. Some subsystem also offer tools to collect relevant
> +   information. One such tool is ``alsa-info.sh`` `which the audio/sound
> +   subsystem developers provide <https://www.alsa-project.org/wiki/AlsaInfo>`_.
> +
> +That will give your some ideas what data might be wise to send, but you have to

                            ideas of what data

> +think yourself what might be helpful for others to know. Don't worry too much
> +about forgetting something: developers will ask for additional details they
> +need; but making everything important available from the start increases the
> +chance someone will take a closer look.
> +
> +The important part: the head of your report
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Now that you have the detailed part of the report prepared let's get back to
> +the most important section: the first few sentences. Thus go to the top, add
> +something like 'The detailed description:' before the part you wrote and insert
> +two newlines at the top. Now write one normal length paragraph that describes
> +the issue roughly. Leave out all boring details and focus on the crucial parts
> +readers need to know to understand what this is all about; if you think this
> +bug affects a lot of users, mention this to get people interested.
> +
> +Once you did that insert two more lines at the top and write a one sentence
> +summary that explains quickly what the report is about. After that you have to
> +get even more abstract and write an even short subject/title for the report.

                                            shorter

> +
> +Now that you have written this part take some time to optimize it, as it is the
> +most important parts of your report: a lot of people will only read this before
> +they decide if reading the rest is time well spend.

                                                spent.

> +
> +Now 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 it's one of those 'issues of high priority' outlined earlier:
> +In that read the next subsection before sending the report.
> +
> +Special handling for high priority issues
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +High priority issues need special handling when sending the report:
> +
> +
> + * *Regression* If the issue is a regression add [REGRESSION] to the mails

                                                                        mail's

> +   subject or the title in the bug-tracker. If you did not perform a bisection
> +   mention at least the latest mainline version you tested that worked fine (say
> +   5.7) and the oldest where the issue occurs (say 5.8). If you did a successful
> +   bisection mention the commit id and subject of the change that causes the
> +   regression. Also make sure to add the author of that change to your report;
> +   if you need to file your bug in a bug-tracker forward the report to him in a
> +   private mail and mention where your filed it.
> +
> + * *Severe bug*: make sure the subject or ticket title as well as the first para

                                                                               paragraph

> +   makes the severeness obvious.
> +
> + * *Security issues*: for these issues your will have to evaluate if a
> +   short-term risk to other users would arise if details were publicly
> +   disclosed. If that's not the case simply proceed with reporting the issue as
> +   described. For issues that bear such a risk you will need to adjust the
> +   reporting process slightly:
> +
> +   * If the MAINTAINERS file instructed you to report the issue by mail, do not
> +     CC any public mailing lists.
> +
> +   * If you were supposed to file the issue in a bug tracker make sure to mark
> +     the ticket as 'private' or 'security issue'. If the bug tracker does not
> +     offer a way to keep reports private, forget about it and send your report
> +     as a private mail to the maintainers instead.
> +
> +   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...
                                                           report's

> +   of it put a small note where you mention that you filed it with a link to the
> +   ticket.
> +
> +   See :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more
> +   information.
> +
> +
>  .. ############################################################################
>  .. 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.
> @@ -867,55 +1065,6 @@ How to report Linux kernel bugs
>  ===============================
>  
>  
> -Gather information
> -------------------
> -
> -The most important information in a bug report is how to reproduce the
> -bug.  This includes system information, and (most importantly)
> -step-by-step instructions for how a user can trigger the bug.
> -
> -If the failure includes an "OOPS:", take a picture of the screen, capture
> -a netconsole trace, or type the message from your screen into the bug
> -report.
> -
> -This is a suggested format for a bug report sent via email or bugzilla.
> -Having a standardized bug report form makes it easier for you not to
> -overlook things, and easier for the developers to find the pieces of
> -information they're really interested in.  If some information is not
> -relevant to your bug, feel free to exclude it.
> -
> -First run the ver_linux script included as scripts/ver_linux, which
> -reports the version of some important subsystems.  Run this script with
> -the command ``awk -f scripts/ver_linux``.
> -
> -Use that information to fill in all fields of the bug report form, and
> -post it to the mailing list with a subject of "PROBLEM: <one line
> -summary from [1.]>" for easy identification by the developers::
> -
> -  [1.] One line summary of the problem:
> -  [2.] Full description of the problem/report:
> -  [3.] Keywords (i.e., modules, networking, kernel):
> -  [4.] Kernel information
> -  [4.1.] Kernel version (from /proc/version):
> -  [4.2.] Kernel .config file:
> -  [5.] Most recent kernel version which did not have the bug:
> -  [6.] Output of Oops.. message (if applicable) with symbolic information
> -       resolved (see Documentation/admin-guide/bug-hunting.rst)
> -  [7.] A small shell script or example program which triggers the
> -       problem (if possible)
> -  [8.] Environment
> -  [8.1.] Software (add the output of the ver_linux script here)
> -  [8.2.] Processor information (from /proc/cpuinfo):
> -  [8.3.] Module information (from /proc/modules):
> -  [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem)
> -  [8.5.] PCI information ('lspci -vvv' as root)
> -  [8.6.] SCSI information (from /proc/scsi/scsi)
> -  [8.7.] Other information that might be relevant to the problem
> -         (please look in /proc and include all information that you
> -         think to be relevant):
> -  [X.] Other notes, patches, fixes, workarounds:
> -
> -
>  Follow up
>  =========
>  


-- 
~Randy