lkml.org 
[lkml]   [2021]   [Mar]   [15]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
From
SubjectRe: [PATCH v2 2/2] docs: reporting-issues.rst: shortcut for reporting stable regressions
Date
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

\
 
 \ /
  Last update: 2021-03-15 21:11    [W:0.054 / U:2.076 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site