Re: [RFC PATCH v1 05/26] docs: reporting-bugs: begin reference section providing details

[Randy Dunlap <rdunlap@infradead.org>]

Hi--

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Provide an introduction to the reference section that will provide more
> details how to report an issue. Mention a few general things here. Those
> are not strictly needed, but likely wise to write down somewhere.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> 
> = RFC =
> 
> Should we keep the links to
> https://www.chiark.greenend.org.uk/~sgtatham/bugs.html and
> http://www.catb.org/esr/faqs/smart-questions.html? Are they worth it? Or is
> there anything similar or better that's a bit fresher and ideally still
> maintained?

Dunno. They are interesting but outdated.

> ---
>  Documentation/admin-guide/reporting-bugs.rst | 46 +++++++++++++++++---
>  1 file changed, 40 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index e0a6f4328e87..be1bce8d43aa 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -205,6 +205,46 @@ rebased on new stable or longterm releases. If that case follow these steps:
>     stable mailing list.
>  
>  
> +Reference section: Reporting issues to the kernel maintainers
> +=============================================================
> +
> +The detailed guides above outlines all the mayor steps in brief fashion, which

                             outline          major

> +should be enough for most people. But sometimes there are situations where even
> +experienced users might wonder how to actually do one of those steps. That's
> +what this section is for, as it will provide a lot more details on each of the
> +steps. Consider this a reference documentation: it's possible to read it from

                        as

> +top to bottom, but more meant to skim over and a place to look up details in
> +case you need them.
> +
> +A few words of general advice before digging into the details:
> +
> + * The Linux kernel developers are well aware this process is complicated and
> +   demands more than other FLOSS projects. We'd love to make it simpler, but
> +   that would require work in various places as well as infrastructure that
> +   would need constant maintenance; nobody has stepped up to do that work, so
> +   that's just how things are for now.
> +
> + * A warranty or support contract with some vendor doesn't entitle you to
> +   request fixes from developers in the upstream Linux kernel community: such
> +   contracts are completely outside the scope of the Linux kernel, its
> +   development community, and this document. That's why you can't demand
> +   anything such a contract guarantees in this context, not even if the
> +   developer handling the issue works for the vendor in question. If you want to
> +   claim your rights, use the vendors support channel instead. When doing so,

                                 vendor's

> +   you might want to mention you'd like to see the issue fixed in the upstream
> +   Linux kernel; motivate them by saying it's the only way to ensure the fix in
> +   the end will get incorporated in all Linux distributions.
> +
> + * If you never reported an issue to a FLOSS project before you should consider
> +   reading `How to Report Bugs Effectively
> +   <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
> +   and `How To Ask Questions The Smart Way
> +   <http://www.catb.org/esr/faqs/smart-questions.html>`_.
> +
> +With that of the table, find below the details on how to properly report issues

             off

> +to the Linux kernel developers.
> +
> +
>  .. ############################################################################
>  .. 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.
> @@ -281,12 +321,6 @@ http://vger.kernel.org/lkml/).
>  Tips for reporting bugs
>  -----------------------
>  
> -If you haven't reported a bug before, please read:
> -
> -	https://www.chiark.greenend.org.uk/~sgtatham/bugs.html
> -
> -	http://www.catb.org/esr/faqs/smart-questions.html
> -
>  It's REALLY important to report bugs that seem unrelated as separate email
>  threads or separate bugzilla entries.  If you report several unrelated
>  bugs at once, it's difficult for maintainers to tease apart the relevant
> 


-- 
~Randy