From: Thorsten Leemhuis <linux@leemhuis.info>
To: Jonathan Corbet <corbet@lwn.net>
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: Sun, 15 Nov 2020 11:13:52 +0100 [thread overview]
Message-ID: <458eb542-ff4d-e734-67fd-01e8378d4864@leemhuis.info> (raw)
In-Reply-To: <20201113153313.68ff210c@lwn.net>
Am 13.11.20 um 23:33 schrieb Jonathan Corbet:
> On Thu, 12 Nov 2020 18:58:37 +0100
> Thorsten Leemhuis <linux@leemhuis.info> wrote:
>
>> This series rewrites the "how to report bugs to the Linux kernel
>> maintainers" document to make it more straight forward and its essence
>> easier to grasp. At the same time make the text provide a lot more details
>> about the process in form of a reference section, so users that want or
>> need to know them have them at hand.
>>
>> The goal of this rewrite: improve the quality of the bug reports and
>> reduce the number of reports that get ignored. This was motivated by many
>> reports of poor quality the submitter noticed while looking after Linux
>> kernel regression tracking many moons ago.
>
> So I've not had a chance to try to read through the whole thing again,
> will try to do so in the near future.
Great, thx, looking forward to it.
> As for how to proceed...getting others to review this is going to be a bit
> of a challenge.
Yeah :-/
> Perhaps the right approach is to just merge the new
> document under a new name - reporting-bugs-the-novel.txt
drivers/staging/Documentation/ (no, just kidding [I think…])
> or something -
> then try to get a few people to look at specific parts of it? Once all
> seems well we can rename it over the old document and call it done.
>
> Make sense?
Totally fine for me. Putting it some place that makes it easier to
collaborate and to see who writes what is better for everyone – and get
control out of my hands and burden off my shoulders. ;-)
There is just one thing on I'm wondering: should we start with the
version of the text start users very long lines/is unwrapped and use it
for the reviewing and polishing phase? Together with tools like meld of
kdiff3 that afaics makes it lot easier to see what actually changes.
That'd why I uploaded the text in such a format:
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs/Documentation/admin-guide/reporting-bugs-v1.rst
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs/Documentation/admin-guide/reporting-bugs-v2.rst
These for example would have allowed an easier rereview from Randy (but
I think he's right not doing one right now [see the other reply]!), as
these tools are quite well at highlighting what changed and what did
not. Yer, these tools are not as bad as a classic diff once you change
something in a wrapped paragraph, but in my experience work quite a bit
better with long lines. That's why I wonder if we should stick to them
before we call the main work done. Another reasons: with long lines
everyone can temporarily put the text in LibreOffice, Google Docs, ...
and use their spelling and grammar checkers.
Another aspect on my mind: the split up makes it easy to just CC certain
people on parts we want them to review. I for example planned to CC the
members of the stable-team only on four patches (TLDR, the two patches
with the step by step parts, the reference section for stable and
logterm), as those are the main ones that are relevant for them:
https://lore.kernel.org/lkml/b80b1387cf09fb897f4a527bc487fff3012d1181.1605203187.git.linux@leemhuis.info/
https://lore.kernel.org/lkml/b439c3d74c541d4d7631203a52f9d697ea8c283d.1605203187.git.linux@leemhuis.info/
https://lore.kernel.org/lkml/2d840fb91b7c5d481284275dea1d4f75fd755af6.1605203187.git.linux@leemhuis.info/
https://lore.kernel.org/lkml/0bb6bf554ac1f0c2a75631e6969a50dcd34c6b51.1605203187.git.linux@leemhuis.info/
Without a split split we'd have to tell people something like "please
took at the document <here> and the sections starting with <foo>, <bar>,
and <baz>". Or would we at some point just simply sent those parts as
regular text (not as diff) my mail to the people & lists that need to
review them?
And a few more thoughts, just for completeness.
* I guess we should discuss the dual-license approach I chose soon
before it gets complicate to change it
* Some of the reviewer might want to compare the approaches the old and
the new text take. The current patch-series tries to makes that easy by
removing parts from the old text when adding new text about that topic.
That would be mostly lost afaics, but I guess it's not that much of a
problem.
* I wonder if putting the text in some real collaborative text editor
(google docs, a wiki, Etherpad, …) for a while would be even better. But
even with restricted write access that might pose some problems for
signing the changes off later. :-/ Guess finding the solution for those
might not be worth the trouble.
Ciao, Thorsten
next prev parent reply other threads:[~2020-11-15 10:14 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 [this message]
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
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=458eb542-ff4d-e734-67fd-01e8378d4864@leemhuis.info \
--to=linux@leemhuis.info \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--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).