Re: [PATCH v2 2/2] docs: reporting-issues.rst: shortcut for reporting stable regressions

[Jonathan Corbet <corbet@lwn.net>]

Thorsten Leemhuis <linux@leemhuis.info> writes:

> Provide a much shorter and easier process for users that deal with
> regressions in stable and longterm kernels, as those should be reported
> quickly.
>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> CC: Randy Dunlap <rdunlap@infradead.org>

Seems generally good, but I had a couple of comments...

> v2
> * revist, lots of small improvements in various places
>
> v1
> * https://lore.kernel.org/linux-doc/20210214145454.357392-1-linux@leemhuis.info/
> * initial version
> ---
>  .../admin-guide/reporting-issues.rst          | 140 ++++++++++++------
>  1 file changed, 94 insertions(+), 46 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
> index 24ee78455d3e..937797e52837 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -106,6 +106,10 @@ process won't feel wasted in the end:
>     issue, or a really severe problem: those are 'issues of high priority' that
>     need special handling in some steps that are about to follow.
>  
> + * If you are facing a regression within a stable or longterm version line
> +   (say something broke when updating from 5.10.4 to 5.10.5), head over to
> +   'Dealing with regressions within a stable and longterm kernel line'.

I would s/head over/scroll down/.  Otherwise readers may well wondering
where to go to find this section.

>   * 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, as issues typically need to be sent
> @@ -215,23 +219,42 @@ rebased on new stable or longterm releases. If that case follow these steps:
>     deemed unsuitable for backporting. If backporting was not considered at
>     all, join the newest discussion, asking if it's in the cards.
>  
> - * Check if you're dealing with a regression that was never present in
> -   mainline by installing the first release of the version line you care
> -   about. If the issue doesn't show up with it, you basically need to report
> -   the issue with this version like you would report a problem with mainline
> -   (see above). This ideally includes a bisection followed by a search for
> -   existing reports on the net; with the help of the subject and the two
> -   relevant commit-ids. If that doesn't turn up anything, write the report; CC
> -   or forward the report to the stable maintainers, the stable mailing list,
> -   and those who authored the change. Include the shortened commit-id if you
> -   found the change that causes it.
> -
>   * One of the former steps should lead to a solution. If that doesn't work
>     out, ask the maintainers for the subsystem that seems to be causing the
>     issue for advice; CC the mailing list for the particular subsystem as well
>     as the stable mailing list.
>  
>  
> +Dealing with regressions within a stable and longterm kernel line
> +-----------------------------------------------------------------
> +
> +This section is for you, if you face a regression within a stable or longterm
> +kernel version line, e.g. if something breaks when updating from 5.10.4 to
> +5.10.5 (a switch from 5.9.15 to 5.10.5 would not qualify). The developers want
> +to fix such regressions as quickly as possible, hence there is a streamlined
> +process to report them:
> +
> + * Check the archives of the Linux stable mailing list for existing reports.
> +
> + * Check if the kernel developers still maintain the Linux kernel version
> +   line you care about: go to the front page of kernel.org and make sure it
> +   mentions the latest release of the particular version line without an
> +   '[EOL]' tag.
> +
> + * Install the latest release from the particular version line as a vanilla
> +   kernel. Ensure this kernel is not tainted and still shows the problem, as
> +   the issue might have already been fixed there.
> +
> + * Make sure it's not the kernel's surroundings that are causing the issue
> +   you face.

I can imagine that a lot of readers would have no idea what that means.
In fact, I'm not entirely sure what that means...

> + * Send a short problem report by mail to the people and mailing lists the
> +   :ref:`MAINTAINERS <maintainers>` file specifies in the section 'STABLE
> +   BRANCH'. Roughly describe the issue and ideally explain how to reproduce
> +   it. Mention the first version that shows the problem and the last version
> +   that's working fine. Then wait for further instructions.
> +
> +
>  Reference section: Reporting issues to the kernel maintainers
>  =============================================================
>  
> @@ -433,6 +456,22 @@ fatal error where the kernel stop itself) with a 'Oops' (a recoverable error),
>  as the kernel remains running after the latter.
>  
>  
> +Regression in stable or longterm kernel?
> +----------------------------------------
> +
> +    *If you are facing a regression within a stable or longterm version line
> +    (say something broke when updating from 5.10.4 to 5.10.5), head over to
> +    'Dealing with regressions within a stable and longterm kernel line'.*

So you want to send them back upward here?

> +Regression within a stable and longterm kernel version line are something the
> +Linux developers want to fix badly, as such issues are even more unwanted than
> +regression in the main development branch, as they can quickly affect a lot of
> +people. The developers thus want to learn about such issues as quickly as
> +possible, hence there is a streamlined process to report them. Note,
> +regressions with newer kernel version line (say something broke when switching
> +from 5.9.15 to 5.10.5) do not qualify.

Given the length of this file, I really wonder if there isn't some way
to cut back on the amount of repeated text?

Thanks,

jon