Date:   Sat, 3 Oct 2020 10:05:24 +0200
From:   Thorsten Leemhuis <linux@...mhuis.info>
To:     Randy Dunlap <rdunlap@...radead.org>,
        Jonathan Corbet <corbet@....net>
Cc:     linux-doc@...r.kernel.org,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Subject: Re: [RFC PATCH v1 03/26] docs: reporting-bugs: step-by-step guide on
 how to report issues

Many thx for you comments. Consider all the obvious spelling and
grammatical mistakes you pointed out fixed, I won't mention all of them
in this reply to keep things easier to follow.

Am 02.10.20 um 05:02 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> […]
>> +brief for you, look up the details in the reference section below, where each
>> +of the steps is explained in more detail.
>> +
>> +Note, this section covers a few more aspects than the TL;DR and does things in a
>    Note:

Ohh, really? LanguageTool suggested to use the comma once when I forgot
a colon, so I assumed it was okay. Uhhps.


>> + * Reproduce the issue with the kernel you just installed. If it doesn't show up
>> +   there, head over to the instructions for issues only happening with stable
>> +   and longterm kernels if you want to see it fixed there.
> Can you link (reference) to that section?

I raised that problem in the cover letter, as this is not the only place
where it would make sense. Hoping for input from Jonathan here how to do
that without adding lots of anchors...

>> + * Optimize your notes: try to find and write the most straightforward way to
>> +   reproduce your issue. Make sure the end result has all the important details,
>> +   and at the same time is easy to read and understand for others that hear
>> +   about it for the first time. And if you learned something in this process,
>> +   consider searching again for existing reports about the issue.
>> +
>> + * If the failure includes a stack dump, like an Oops does, consider decoding it
>> +   to find the offending line of code.
> Refer to scripts/decodecode ?
> or is that done elsewhere?

Elsewhere and this step and that document likely needs to be heavily
updated anyway, as pointed out in a later patch :-/

>> +
>> + * If your problem is a regression, try to narrow down when the issue was
>> +   introduced as much as possible.
>> +
>> + * Start to compile the report by writing a detailed description about the
>> +   issue. Always mentions a few things: the latest kernel version you installed
>> +   for reproducing, the Linux Distribution used, and your notes how to
> 
> I would say:                                                 notes on how to
> Maybe it's just me.

Googled a bit and to me as a non-native English speaker looks like
you're correct.

>> +   reproduce the issue. Ideally, make the kernels build configuration (.config)
>                                              kernel's

Uggh, sorry, this mistake will show up a few more times, looks like I
applied German grammar rules to English. :-/

>> +   the issue and the impact quickly. On top of this add one sentence that
>> +   briefly describes the problem and gets people to read on. Now give the thing
>> +   a descriptive title or subject that yet again is shorter. Then you're ready
>> +   to send or file the report like the `MAINTAINERS file
>> +   <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
>> +   told you, unless you are dealing with one of those 'issues of high priority':
>       tells you,
> OK, I like present tense as much as possible.

Hmmm. Normally I'd agree, but I used past tense here because it refers
to something the reader did in an earlier step.

>> + * Wait for reactions and keep the thing rolling until you can accept the
>> +   outcome in one way or the other. Thus react publicly and in a timely manner
>> +   to any inquiries. Test proposed fixes. Do proactive testing when a new rc1
>                                                                   when a new -rc
> (release candidate) is released. Send

I only meant "rc1" here, not every rc. More about this in a later patch.

Regarding explaining "rc" as "release candidate": my stupid brain has a
really hard time following that suggestion, as it still remembers some
words someone named Linus Torvalds wrote many many years ago:
```
I'll just use "-rc", and we can all agree that it stands for "Ridiculous
Count" rather than "Release Candidate".
```
https://lore.kernel.org/lkml/Pine.LNX.4.58.0410221821030.2101@ppc970.osdl.org/


I'll go and try to find some pills to force my brain into compliance.
;-) Once they start to work it hopefully can agree to this:

Do proactive testing: retest with at least every first release candidate
(RC) of a new mainline version and report your results.

Ciao, Thorsten

Powered by blists - more mailing lists