Re: [RFC PATCH v1 15/26] docs: reporting-bugs: make readers test mainline, but leave a loophole

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Now that the document described all preparatory steps tell users to
> install the latest kernel. Try pretty hard to motivate them installing a
> mainline kernel, as that is best for reporting issues. Mention the
> latest stable kernel as an acceptable alternative, but discourage this
> option. Point out that longterm kernels are unsuitable.
> 
> While at it, provide a few hints how to obtain a fresh kernel. Also
> explain how to find out what the latest version actually is. And mention
> why it might be a good idea to wait till the end of the merge window
> when reporting issues.
> 
> Signed-off-by: Thorsten Leemhuis <linux@xxxxxxxxxxxxx>
> ---
> 
> = RFC =
> 
> Am I asking for too much from users by telling them to test mainline? But most
> will likely have an outdated and heavily patched vendor kernel anyway, so they
> have to install a vanilla kernel if they want to report something upstream;
> that's why I thought "well, then let's go all in and make them test mainline.

That is appropriate IMO.

> ---
>  Documentation/admin-guide/reporting-bugs.rst | 88 ++++++++++++++++++++
>  1 file changed, 88 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index f99d92a05bca..dee6d65aa95c 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -643,6 +643,94 @@ hardware apart from a kernel issue that rarely happens and thus is hard to
>  reproduce.
>  
>  
> +Install the latest mainline kernel
> +----------------------------------
> +
> +    *Install the latest Linux mainline kernel: that's where all issue get fixed

                                                                   issues

> +    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 alternative in some situations, but is best avoided.*

       an acceptable

> +
> +Reporting an issue to the Linux kernel developers they fixed a while ago is
> +annoying for them and wasting their and your time. That's why it's in
> +everybody's interest to check if the issue occurs with the latest version before
> +reporting it.
> +
> +In the scope of the Linux kernel the term 'latest' means: a kernel version
> +recently created from the main line of development, as this 'mainline' tree is
> +where every fix gets applied to first; only later they are allowed to get
> +backported to older, still support version lines called 'stable' and 'longterm'

                              supported

> +kernels. That's why it's a prerequisite to check mainline even if just want to

                                                             even if you just want to

> +see the issue fixed in one of those. Another reasons: sometimes fixes for an

                       in one of those other version lines. Another reason:


> +issue are only applied to mainline, as they are too risky to get backported
> +into older version lines where they thus remain unfixed.
> +
> +It's thus in your and everybody's else interest to reproduce the issue with a

                         everybody else's

> +fresh mainline kernel before reporting it. Reproducing it with the latest Linux
> +'stable' kernel can be acceptable alternative, if you can't test mainline for
> +some reason; this is not ideal, but better than not reporting the issue at all.
> +
> +Avoid testing with one of the longterm kernels (sometimes called "LTS kernels"),
> +they are too distant from current development; the same is also true for

   as they are too distant

> +mainline or stable kernels that are not very recent, as there is a new release
> +of those nearly every week.
> +
> +Ways to obtains a fresh vanilla kernel
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +One way to get the latest mainline or stable kernel in a vanilla fashion is to
> +download the Linux sources from `kernel.org <https://kernel.org/>`_ and build a
> +kernel image and modules from them yourself. How to do that is not described
> +here, as many texts on the internet explain the necessary steps already. If you
> +are new to it, consider following one of those how-to's that suggest to use
> +``make localmodconfig``, as that tries to pick up the configuration of your
> +current kernel and then tries to adjust it somewhat for your system. That does
> +not make the resulting kernel any better, but makes it compile a lot faster.
> +
> +There might be a way around building your own kernel, if you are in a luck: for

                                                                    in luck: for

> +popular Linux distribution you'll find repositories on the net that offer
> +packages with of the latest mainline or stable Linux vanilla kernels for easy
> +installation. It's totally okay to use packages with these pre-compiled kernels,
> +just make sure from the repository's documentation they are supposed to be
> +'vanilla', for reasons outlined in the first step of this process. And be aware
> +that you might need to build your own kernel later anyway when it comes to
> +testing fixes, as described later in this document.
> +
> +Finding the latest Linux version
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +To check what the latest mainline release actually is, go to `kernel.org
> +<https://kernel.org/>`_. Ignore the big yellow button that says 'Latest
> +release': that points to the latest stable release, which you normally don't
> +want to use.
> +
> +Instead, look a little lower for a table for a line with the description

                                            with a line with the description

> +'mainline', which you'll find at the top of that table. Most of the time
> +'mainline' will point to a pre-release with a version number like '5.8-rc2'. In
> +that case that's the version you want to test. Do not let that 'rc' scare you,
> +these 'development kernels' are pretty reliable — and you have a backup, like we
> +told you above, don't you?
> +
> +In about two out of every nine to ten weeks, 'mainline' might point you to a
> +proper release with a version number like '5.7'. If that happens consider
> +suspending the reporting process for a while, as the Linux development cycle is
> +currently in its two-week long 'merge window'. That's where the bulk of the
> +changes (and all intrusive ones) get merged for the next release, before its
> +first pre-release is published (5.8-rc1). Kernel developers are often quite
> +busy during this time period and might have no spare time to deal with issue
> +reports. It's also quite possible that one of the many changes applied during
> +the merge window fixes the issue you face; that's why you soon would have to
> +retest with a newer kernel version anyway, as outlined below in the section
> +'Duties after the report when out'. Therefor it's often wise to wait for the

                                       Therefore

> +first pre-release before proceeding with this step, unless you're dealing with
> +one of those 'issues of high priority' or one that can't wait for a good reason.
> +
> +Feel free to ignore the past three paragraphs if you are a developer, Linux
> +kernel expert, or brave; instead simply get the latest Linux kernel sources
> +using ``git`` straight from the `official development repository on kernel.org
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_.
> +
> +
>  .. ############################################################################
>  .. 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