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

[Thorsten Leemhuis <linux@leemhuis.info>]

On 15.03.21 21:11, Jonathan Corbet wrote:
> 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...

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