Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

From: Jonathan Corbet
Date: Fri Nov 20 2020 - 16:58:15 EST


On Fri, 20 Nov 2020 11:46:07 +0100
Thorsten Leemhuis <linux@xxxxxxxxxxxxx> wrote:

> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
> > On Sun, 15 Nov 2020 11:13:52 +0100
> > Thorsten Leemhuis <linux@xxxxxxxxxxxxx> wrote:
>
> > - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
> > (or some suitable name). I do wonder if it should also move to the
> > process manual as part of this; not only admins will report bugs.
>
> After a night's sleep and Randy's comment I for now settled on
> Documentation/admin-guide/reporting-issues.rst

Keeping it in the admin guide is OK. Not sure about the name, though; if
you're really dead set against bugs, maybe reporting-problems.rst?

> > - Add a comment at the top saying it's a proposed replacement and
> > soliciting comments. [...]
> Struggled a bit to find the right words, but I think this should work:
>
> ```
> .. important::
>
> This document is being prepared to replace
> Documentation/admin-guide/reporting-bugs.rst. The main work is done and
> you are already free to follow its instructions when reporting issues to
> the Linux kernel developers. But keep in mind, below text still needs a
> few finishing touches and review. It was merged to the Linux kernel
> sources at this stage to make this process easier and increase the
> text's visibility.
>
> Any improvements for the text or other feedback is thus very much
> welcome. Please send it to 'Thorsten Leemhuis <linux@xxxxxxxxxxxxx>' and
> 'Jonathan Corbet <corbet@xxxxxxx>', ideally with 'Linux kernel mailing
> list (LKML) <linux-kernel@xxxxxxxxxxxxxxx>' and the 'Linux Kernel
> Documentation List <linux-doc@xxxxxxxxxxxxxxx>' in CC.
>
> Areas in the text that still need work or discussion contain a hint
> like this which point out the remaining issues; all of them start with
> the word "FIXME" to make them easy to find.
> ```

Seems OK.

> > - In a separate patch you could add a comment to the existing document
> > pointing to the new one as the true source of wisdom.
>
> This is what I plan to add:
>
> ```
> .. note::
>
> Instead of reading below text consider reading this document
> instead: Documentation/admin-guide/reporting-issues.rst. It's intended
> to replace below text in the near future, as it's easier to grasp and
> more straight forward; it also provides way more details and more
> accurately describes the steps currently needed when reporting bugs to
> the Linux developers.
> ```

I'd be a bit more straightforward:

This document is obsolete, and will be replaced by
Documentation/admin-guide/$NAME in the near future.

Not sure that more is really needed?

jon