From: Jonathan Corbet <corbet@lwn.net>
To: Thorsten Leemhuis <linux@leemhuis.info>
Cc: Randy Dunlap <rdunlap@infradead.org>,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful
Date: Fri, 20 Nov 2020 14:58:13 -0700 [thread overview]
Message-ID: <20201120145813.76b7b326@lwn.net> (raw)
In-Reply-To: <2dcea97c-7b98-1ad2-d2ba-e7f7d77dc855@leemhuis.info>
On Fri, 20 Nov 2020 11:46:07 +0100
Thorsten Leemhuis <linux@leemhuis.info> wrote:
> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
> > On Sun, 15 Nov 2020 11:13:52 +0100
> > Thorsten Leemhuis <linux@leemhuis.info> 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@leemhuis.info>' and
> 'Jonathan Corbet <corbet@lwn.net>', ideally with 'Linux kernel mailing
> list (LKML) <linux-kernel@vger.kernel.org>' and the 'Linux Kernel
> Documentation List <linux-doc@vger.kernel.org>' 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
next prev parent reply other threads:[~2020-11-20 21:58 UTC|newest]
Thread overview: 43+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-12 17:58 [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 01/26] docs: reporting-bugs: temporary markers for licensing and diff reasons Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 02/26] docs: reporting-bugs: Create a TLDR how to report issues Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 03/26] docs: reporting-bugs: step-by-step guide on " Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 04/26] docs: reporting-bugs: step-by-step guide for issues in stable & longterm Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 05/26] docs: reporting-bugs: begin reference section providing details Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 06/26] docs: reporting-bugs: point out we only care about fresh vanilla kernels Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 07/26] docs: reporting-bugs: let users classify their issue Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 08/26] docs: reporting-bugs: make readers check the taint flag Thorsten Leemhuis
2020-11-19 0:05 ` Jonathan Corbet
2020-11-19 10:26 ` Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 09/26] docs: reporting-bugs: help users find the proper place for their report Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 10/26] docs: reporting-bugs: remind people to look for existing reports Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 11/26] docs: reporting-bugs: remind people to back up their data Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 12/26] docs: reporting-bugs: tell users to disable DKMS et al Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 13/26] docs: reporting-bugs: point out the environment might be causing issue Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 14/26] docs: reporting-bugs: make users write notes, one for each issue Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 15/26] docs: reporting-bugs: make readers test a fresh kernel Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 16/26] docs: reporting-bugs: let users check taint status again Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 17/26] docs: reporting-bugs: explain options if reproducing on mainline fails Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 18/26] docs: reporting-bugs: let users optimize their notes Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 19/26] docs: reporting-bugs: decode failure messages [need help!] Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 20/26] docs: reporting-bugs: instructions for handling regressions Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 21/26] docs: reporting-bugs: details on writing and sending the report Thorsten Leemhuis
2020-11-19 0:17 ` Jonathan Corbet
2020-11-19 9:42 ` Thorsten Leemhuis
2020-11-12 17:58 ` [RFC PATCH v2 22/26] docs: reporting-bugs: explain what users should do once the report is out Thorsten Leemhuis
2020-11-12 17:59 ` [RFC PATCH v2 23/26] docs: reporting-bugs: details for issues specific to stable and longterm Thorsten Leemhuis
2020-11-12 17:59 ` [RFC PATCH v2 24/26] docs: reporting-bugs: explain why users might get neither reply nor fix Thorsten Leemhuis
2020-11-12 17:59 ` [RFC PATCH v2 25/26] docs: reporting-bugs: explain things could be easier Thorsten Leemhuis
2020-11-12 17:59 ` [RFC PATCH v2 26/26] docs: reporting-bugs: add SPDX tag and license hint, remove markers Thorsten Leemhuis
2020-11-13 22:33 ` [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful Jonathan Corbet
2020-11-13 22:47 ` Randy Dunlap
2020-11-15 10:13 ` Thorsten Leemhuis
2020-11-19 0:29 ` Jonathan Corbet
2020-11-19 12:29 ` Thorsten Leemhuis
2020-11-19 16:20 ` Randy Dunlap
2020-11-20 21:59 ` Jonathan Corbet
2020-11-20 10:46 ` Thorsten Leemhuis
2020-11-20 16:27 ` Randy Dunlap
2020-11-20 21:58 ` Jonathan Corbet [this message]
2020-11-22 5:33 ` Thorsten Leemhuis
2020-11-22 5:42 ` Randy Dunlap
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201120145813.76b7b326@lwn.net \
--to=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux@leemhuis.info \
--cc=rdunlap@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).