Re: [PATCH v1] docs: reporting-issues.rst: CC subsystem and maintainers on regressions

From: Thorsten Leemhuis
Date: Wed Apr 28 2021 - 02:35:59 EST


Hi Jonathan. Wondering if this slipped through the cracks, as I haven't
heart anything (or did I miss it?). Would IMHO have been nice to have in
5.13 as well, but it's not crucial.

On 15.04.21 12:29, Thorsten Leemhuis wrote:
> When reporting a regression, users ideally should CC the subsystem and
> its maintainers, as that will ensure they get aware of the regression
> quickly. And if the culprit is known, they should also CC everyone who
> signed if off; the text mentioned the latter in once place already, but

Side note (just spotted this from a corner of my eye): s/once/one/ in
that line.

Ciao, Thorsten

> forgot to do so in two other areas where it's relevant.
>
> While fixing this also remind readers to check the mailing list archives
> for issues that need to be reported to a bug tracker, as someone might
> have reported it by mail only.
>
> All of this got triggered by a recent report where these changes would
> have made a difference.
>
> Link: https://lore.kernel.org/lkml/dff6badf-58f5-98c8-871c-94d901ac6919@xxxxxxxxxxxxx/
> Link: https://lore.kernel.org/lkml/CAJZ5v0hX2StQVttAciHYH-urUH+Hi92z9z2ZbcNgQPt0E2Jpwg@xxxxxxxxxxxxxx/
> Signed-off-by: Thorsten Leemhuis <linux@xxxxxxxxxxxxx>
> ---
> .../admin-guide/reporting-issues.rst | 49 ++++++++++++-------
> 1 file changed, 30 insertions(+), 19 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
> index 48b4d0ef2b09..18d8e25ba9df 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -24,7 +24,8 @@ longterm series? One still supported? Then search the `LKML
> you don't find any, install `the latest release from that series
> <https://kernel.org/>`_. If it still shows the issue, report it to the stable
> mailing list (stable@xxxxxxxxxxxxxxx) and CC the regressions list
> -(regressions@xxxxxxxxxxxxxxx).
> +(regressions@xxxxxxxxxxxxxxx); ideally also CC the maintainer and the mailing
> +list for the subsystem in question.
>
> In all other cases try your best guess which kernel part might be causing the
> issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its developers
> @@ -48,8 +49,9 @@ before the issue occurs.
> If you are facing multiple issues with the Linux kernel at once, report each
> separately. While writing your report, include all information relevant to the
> issue, like the kernel and the distro used. In case of a regression, CC the
> -regressions mailing list (regressions@xxxxxxxxxxxxxxx) to your report; also try
> -to include the commit-id of the change causing it, which a bisection can find.
> +regressions mailing list (regressions@xxxxxxxxxxxxxxx) to your report. Also try
> +to pin-point the culprit with a bisection; if you succeed, include its
> +commit-id and CC everyone in the sign-off-by chain.
>
> Once the report is out, answer any questions that come up and help where you
> can. That includes keeping the ball rolling by occasionally retesting with newer
> @@ -198,10 +200,11 @@ report them:
>
> * Send a short problem report to the Linux stable mailing list
> (stable@xxxxxxxxxxxxxxx) and CC the Linux regressions mailing list
> - (regressions@xxxxxxxxxxxxxxx). 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.
> + (regressions@xxxxxxxxxxxxxxx); if you suspect the cause in a particular
> + subsystem, CC its maintainer and its mailing list. 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.
>
> The reference section below explains each of these steps in more detail.
>
> @@ -768,7 +771,9 @@ regular internet search engine and add something like
> the results to the archives at that URL.
>
> It's also wise to check the internet, LKML and maybe bugzilla.kernel.org again
> -at this point.
> +at this point. If your report needs to be filed in a bug tracker, you may want
> +to check the mailing list archives for the subsystem as well, as someone might
> +have reported it only there.
>
> For details how to search and what to do if you find matching reports see
> "Search for existing reports, first run" above.
> @@ -1249,9 +1254,10 @@ and the oldest where the issue occurs (say 5.8-rc1).
>
> When sending the report by mail, CC the Linux regressions mailing list
> (regressions@xxxxxxxxxxxxxxx). In case the report needs to be filed to some web
> -tracker, proceed to do so; once filed, forward the report by mail to the
> -regressions list. Make sure to inline the forwarded report, hence do not attach
> -it. Also add a short note at the top where you mention the URL to the ticket.
> +tracker, proceed to do so. Once filed, forward the report by mail to the
> +regressions list; CC the maintainer and the mailing list for the subsystem in
> +question. Make sure to inline the forwarded report, hence do not attach it.
> +Also add a short note at the top where you mention the URL to the ticket.
>
> When mailing or forwarding the report, in case of a successful bisection add the
> author of the culprit to the recipients; also CC everyone in the signed-off-by
> @@ -1536,17 +1542,20 @@ Report the regression
>
> *Send a short problem report to the Linux stable mailing list
> (stable@xxxxxxxxxxxxxxx) and CC the Linux regressions mailing list
> - (regressions@xxxxxxxxxxxxxxx). 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.*
> + (regressions@xxxxxxxxxxxxxxx); if you suspect the cause in a particular
> + subsystem, CC its maintainer and its mailing list. 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.*
>
> When reporting a regression that happens within a stable or longterm kernel
> line (say when updating from 5.10.4 to 5.10.5) a brief report is enough for
> -the start to get the issue reported quickly. Hence a rough description is all
> -it takes.
> +the start to get the issue reported quickly. Hence a rough description to the
> +stable and regressions mailing list is all it takes; but in case you suspect
> +the cause in a particular subsystem, CC its maintainers and its mailing list
> +as well, because that will speed things up.
>
> -But note, it helps developers a great deal if you can specify the exact version
> +And note, it helps developers a great deal if you can specify the exact version
> that introduced the problem. Hence if possible within a reasonable time frame,
> try to find that version using vanilla kernels. Lets assume something broke when
> your distributor released a update from Linux kernel 5.10.5 to 5.10.8. Then as
> @@ -1563,7 +1572,9 @@ pinpoint the exact change that causes the issue (which then can easily get
> reverted to fix the issue quickly). Hence consider to do a proper bisection
> right away if time permits. See the section 'Special care for regressions' and
> the document 'Documentation/admin-guide/bug-bisect.rst' for details how to
> -perform one.
> +perform one. In case of a successful bisection add the author of the culprit to
> +the recipients; also CC everyone in the signed-off-by chain, which you find at
> +the end of its commit message.
>
>
> Reference for "Reporting issues only occurring in older kernel version lines"
>
> base-commit: 6161a4b18a66746c3f5afa72c054d7e58e49c847
>