Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
MIME-Version: 1.0
References: <CAKXUXMy2WfsRj+nJuNCV4bPNYTvDySLOq3HgpK+gWJSpWS81Kg@mail.gmail.com>
 <1dc0ab09-2cfd-a310-d1da-ef7d3cc47a71@leemhuis.info>
In-Reply-To: <1dc0ab09-2cfd-a310-d1da-ef7d3cc47a71@leemhuis.info>
From:   Lukas Bulwahn <lukas.bulwahn@gmail.com>
Date:   Wed, 13 Jul 2022 12:06:51 +0200
Message-ID: <CAKXUXMy4oW-m_-NQDk6DcoyRE5QprwvaCXa0QF6_FLZ7zL-d4w@mail.gmail.com>
Subject: Re: Update "If something goes wrong" in Documentation/admin-guide/README.rst
To:     Thorsten Leemhuis <linux@leemhuis.info>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        "open list:DOCUMENTATION" <linux-doc@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

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