p71924506
/
linux_old1
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: reporting-issues.rst: CC subsystem and maintainers on regressions 

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
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.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/lkml/dff6badf-58f5-98c8-871c-94d901ac6919@leemhuis.info/
Link: https://lore.kernel.org/lkml/CAJZ5v0hX2StQVttAciHYH-urUH+Hi92z9z2ZbcNgQPt0E2Jpwg@mail.gmail.com/
Link: https://lore.kernel.org/r/dd13f10c30e79e550215e53a8103406daec4e593.1618482489.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Thorsten Leemhuis 2021-04-15 12:29:14 +02:00 committed by Jonathan Corbet
parent 2fa4928aed
commit 0043f0b27a
1 changed files with 30 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
Documentation/admin-guide/reporting-issues.rst
View File

@ -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 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 <https://kernel.org/>`_. If it still shows the issue, report it to the stable
mailing list (stable@vger.kernel.org) and CC the regressions list mailing list (stable@vger.kernel.org) and CC the regressions list
(regressions@lists.linux.dev). (regressions@lists.linux.dev); 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 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 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 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 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 issue, like the kernel and the distro used. In case of a regression, CC the
regressions mailing list (regressions@lists.linux.dev) to your report; also try regressions mailing list (regressions@lists.linux.dev) to your report. Also try
to include the commit-id of the change causing it, which a bisection can find. 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 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 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 * Send a short problem report to the Linux stable mailing list
(stable@vger.kernel.org) and CC the Linux regressions mailing list (stable@vger.kernel.org) and CC the Linux regressions mailing list
(regressions@lists.linux.dev). Roughly describe the issue and ideally (regressions@lists.linux.dev); if you suspect the cause in a particular
explain how to reproduce it. Mention the first version that shows the subsystem, CC its maintainer and its mailing list. Roughly describe the
problem and the last version that's working fine. Then wait for further issue and ideally explain how to reproduce it. Mention the first version
instructions. 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. 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. the results to the archives at that URL.
It's also wise to check the internet, LKML and maybe bugzilla.kernel.org again 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 For details how to search and what to do if you find matching reports see
"Search for existing reports, first run" above. "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 When sending the report by mail, CC the Linux regressions mailing list
(regressions@lists.linux.dev). In case the report needs to be filed to some web (regressions@lists.linux.dev). 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 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 regressions list; CC the maintainer and the mailing list for the subsystem in
it. Also add a short note at the top where you mention the URL to the ticket. 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 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 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 *Send a short problem report to the Linux stable mailing list
(stable@vger.kernel.org) and CC the Linux regressions mailing list (stable@vger.kernel.org) and CC the Linux regressions mailing list
(regressions@lists.linux.dev). Roughly describe the issue and ideally (regressions@lists.linux.dev); if you suspect the cause in a particular
explain how to reproduce it. Mention the first version that shows the subsystem, CC its maintainer and its mailing list. Roughly describe the
problem and the last version that's working fine. Then wait for further issue and ideally explain how to reproduce it. Mention the first version
instructions.* 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 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 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 the start to get the issue reported quickly. Hence a rough description to the
it takes. 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, 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 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 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 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 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 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" Reference for "Reporting issues only occurring in older kernel version lines"