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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <1dc0ab09-2cfd-a310-d1da-ef7d3cc47a71@leemhuis.info>
Date:   Wed, 13 Jul 2022 11:41:49 +0200
From:   Thorsten Leemhuis <linux@...mhuis.info>
To:     Lukas Bulwahn <lukas.bulwahn@...il.com>,
        Jonathan Corbet <corbet@....net>,
        "open list:DOCUMENTATION" <linux-doc@...r.kernel.org>
Cc:     Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Subject: Re: Update "If something goes wrong" in
 Documentation/admin-guide/README.rst

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