Re: [PATCH v2 2/2] docs: reporting-issues.rst: shortcut for reporting stable regressions
On 15.03.21 21:11, Jonathan Corbet wrote: > Thorsten Leemhuis 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 >> CC: Randy Dunlap > > Seems generally good, but I had a couple of comments... Thx for your feedback. > […] >> + * 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. Good idea. Used this phrase somewhere else also, addressed it there in a septate patch in the series I just sent: https://lore.kernel.org/linux-doc/cover.1616181657.git.li...@leemhuis.info/ > [...] >> + * 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... That's why it explained in the reference section. That is a bit hard to spot just from the patch. > [...] >> +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? No, this is just repeating the text from the step-by-step guide, as it's done everywhere in the reference section. It's hard to see in the diff and more clear when you look at the document as a whole. >> +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? The latest series addresses this: https://lore.kernel.org/linux-doc/cover.1616181657.git.li...@leemhuis.info/ To avoid repeated text I had to use this in the end: ``` Perform the first three steps in the section "Reporting issues only occurring in older kernel version lines" above. ``` Not ideal, but not too bad and works. Thx again for your suggestions! Ciao, Thorsten
Re: [PATCH v2 2/2] docs: reporting-issues.rst: shortcut for reporting stable regressions
Thorsten Leemhuis 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 > CC: Randy Dunlap 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-li...@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 ` 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? > + > + > +
[PATCH v2 2/2] docs: reporting-issues.rst: shortcut for reporting stable regressions
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 CC: Randy Dunlap --- v2 * revist, lots of small improvements in various places v1 * https://lore.kernel.org/linux-doc/20210214145454.357392-1-li...@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'. + * 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. + + * Send a short problem report by mail to the people and mailing lists the + :ref:`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'.* + +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