Update "If something goes wrong" in Documentation/admin-guide/README.rst

Update "If something goes wrong" in Documentation/admin-guide/README.rst

[Lukas Bulwahn]

Dear Thorsten, dear Jonathan,


During some other unrelated clean-up work, I stumbled upon the section
'If something goes wrong' in Documentation/admin-guide/README.rst
(https://www.kernel.org/doc/html/latest/admin-guide/README.html).
README.rst is---as it seems---the intended first summary page of the
documentation for any user of the kernel (the kernel's release notes
document).

The section 'If something goes wrong' describes what to do when
encountering a bug and how to report it. The second sentence in that
section is especially historic and probably just discouraging for most
bug reporters ( ..."the second best thing is to mail them to me
(torvalds@linux-foundation.org)"...). Some random user (potentially
even unknown to the community) sending an email to Linus is most
probably the last best thing to do and is most likely just ignored,
right?

Probably this section in README.rst needs a rewrite (summarizing
Thorsten's reporting-issues.rst, or just copying the summary from
there) and should then refer to reporting-issues.rst for more details.

Thorsten, do you have time to prepare a change to that document that
gives a short summary on how to report potential issues and
regressions? Otherwise, I will happily put that on my todo list and
probably can suggest some RFC patch in a week or two.


Best regards,

Lukas

Re: Update "If something goes wrong" in Documentation/admin-guide/README.rst

[Thorsten Leemhuis]

Hi! Lukas, thx for bringing this up.

On 13.07.22 09:26, Lukas Bulwahn wrote:
>
> During some other unrelated clean-up work, I stumbled upon the section
> 'If something goes wrong' in Documentation/admin-guide/README.rst
> (https://www.kernel.org/doc/html/latest/admin-guide/README.html).
> README.rst is---as it seems---the intended first summary page of the
> documentation for any user of the kernel (the kernel's release notes
> document).
> 
> The section 'If something goes wrong' describes what to do when
> encountering a bug and how to report it. The second sentence in that
> section is especially historic and probably just discouraging for most
> bug reporters ( ..."the second best thing is to mail them to me
> (torvalds@linux-foundation.org)"...).

Ha, yeah, guess so :-D

> Some random user (potentially
> even unknown to the community) sending an email to Linus is most
> probably the last best thing to do and is most likely just ignored,
> right?

I'd say it depends on the report and would guess Linus in quite a few
cases will act on it if the report at least somewhat good -- or about
something important, like a bisected regression.

> Probably this section in README.rst needs a rewrite (summarizing
> Thorsten's reporting-issues.rst, or just copying the summary from
> there) and should then refer to reporting-issues.rst for more details.

Well, any new summary sounds a bit like 'similar code paths for doing
the same thing'. Sometimes that is necessary when coding, but often it's
best avoided for known reasons. I think it's not that different for docs.

Maybe just copying the "short guide" from the top of
reporting-issues.rst might be the most elegant solution for README.rst
while adding the link your mentioned (maybe while adding a comment to
reporting-issues.rst saying something like 'if you update this section,
update the copy over there, too'). But I'm not sure myself right now if
that's really the best way forward; maybe a few modifications might be
good here. Let's see what Jonathan says.

Note, the section in README.rst you mentioned also contains a few
aspects that reporting-issues.rst despite it's size doesn't cover. :-/
But some of that stuff looks outdated anyway.

> Thorsten, do you have time to prepare a change to that document that
> gives a short summary on how to report potential issues and
> regressions? Otherwise, I will happily put that on my todo list and
> probably can suggest some RFC patch in a week or two.

Then go for it. Normally I'd be interested, but I'm short on time
currently, as I'm working a lot on bugzilla integration for regzbot,
have a vacation coming up, and need to prepare talks for two conferences
(Kernel Summit and Open Source Summit).

Ciao, Thorsten

Re: Update "If something goes wrong" in Documentation/admin-guide/README.rst

[Lukas Bulwahn]

On Wed, Jul 13, 2022 at 11:41 AM Thorsten Leemhuis <linux@leemhuis.info> wrote:
>
> Hi! Lukas, thx for bringing this up.
>
> On 13.07.22 09:26, Lukas Bulwahn wrote:
> >
> > During some other unrelated clean-up work, I stumbled upon the section
> > 'If something goes wrong' in Documentation/admin-guide/README.rst
> > (https://www.kernel.org/doc/html/latest/admin-guide/README.html).
> > README.rst is---as it seems---the intended first summary page of the
> > documentation for any user of the kernel (the kernel's release notes
> > document).
> >
> > The section 'If something goes wrong' describes what to do when
> > encountering a bug and how to report it. The second sentence in that
> > section is especially historic and probably just discouraging for most
> > bug reporters ( ..."the second best thing is to mail them to me
> > (torvalds@linux-foundation.org)"...).
>
> Ha, yeah, guess so :-D
>
> > Some random user (potentially
> > even unknown to the community) sending an email to Linus is most
> > probably the last best thing to do and is most likely just ignored,
> > right?
>
> I'd say it depends on the report and would guess Linus in quite a few
> cases will act on it if the report at least somewhat good -- or about
> something important, like a bisected regression.
>
> > Probably this section in README.rst needs a rewrite (summarizing
> > Thorsten's reporting-issues.rst, or just copying the summary from
> > there) and should then refer to reporting-issues.rst for more details.
>
> Well, any new summary sounds a bit like 'similar code paths for doing
> the same thing'. Sometimes that is necessary when coding, but often it's
> best avoided for known reasons. I think it's not that different for docs.
>
> Maybe just copying the "short guide" from the top of
> reporting-issues.rst might be the most elegant solution for README.rst
> while adding the link your mentioned (maybe while adding a comment to
> reporting-issues.rst saying something like 'if you update this section,
> update the copy over there, too'). But I'm not sure myself right now if
> that's really the best way forward; maybe a few modifications might be
> good here. Let's see what Jonathan says.
>
> Note, the section in README.rst you mentioned also contains a few
> aspects that reporting-issues.rst despite it's size doesn't cover. :-/
> But some of that stuff looks outdated anyway.
>
> > Thorsten, do you have time to prepare a change to that document that
> > gives a short summary on how to report potential issues and
> > regressions? Otherwise, I will happily put that on my todo list and
> > probably can suggest some RFC patch in a week or two.
>
> Then go for it. Normally I'd be interested, but I'm short on time
> currently, as I'm working a lot on bugzilla integration for regzbot,
> have a vacation coming up, and need to prepare talks for two conferences
> (Kernel Summit and Open Source Summit).
>

Then, I will take the points you mentioned as guidance and prepare a
RFC patch and we can discuss what specific changes are needed beyond
my first attempt.

Lukas

Re: Update "If something goes wrong" in Documentation/admin-guide/README.rst

[Jonathan Corbet]

Thorsten Leemhuis <linux@leemhuis.info> writes:

> Maybe just copying the "short guide" from the top of
> reporting-issues.rst might be the most elegant solution for README.rst
> while adding the link your mentioned (maybe while adding a comment to
> reporting-issues.rst saying something like 'if you update this section,
> update the copy over there, too'). But I'm not sure myself right now if
> that's really the best way forward; maybe a few modifications might be
> good here. Let's see what Jonathan says.

Let's not duplicate the text; why not just link over to
reporting-issues.rst?

In general, README.rst has seen little attention for a long time and
could benefit from a major thrashing, methinks.

Thanks,

jon