Re: [PATCH v1, RFC] docs: reporting-issues.rst: tone down 'test vanilla mainline' a little

[Thorsten Leemhuis]

On 16.03.21 18:56, Thorsten Leemhuis wrote:
> On 15.03.21 21:20, Jonathan Corbet wrote:
>> Thorsten Leemhuis  writes:
>
>>  Anything that could be done to
>> make it more concise going forward would be more than welcome.
> Yeah, will think about it, especially WRT to the other patch you looked
> at. Maybe I can come up with something. But no promises, I put a lot of
> thought into the problem already.

FWIW, just sent out a new series that IMHO at least is a small step in
the right direction:

https://lore.kernel.org/linux-doc/cover.1616181657.git.li...@leemhuis.info/

Hard to see in the diffs, might be wise to look at the end result.

I added this patch to the series as things otherwise might get hard to
handle.

>> Also, I would stop quoting terms like "mainline", "stable" and "vanilla"
>> throughout.  It makes the reading experience a bit stranger without
>> (IMO) adding anything.
> Yeah, let me provide a patch to reduce the quoting. If it's okay for you
> I'd like to leave the quotes in the section that round about explains
> the terms mainline, stable, and longterm. I think it's wise there to
> point out that these are terms that have a special meaning in kernel
> context. That's why I quoted them in a lot of places – especially those
> where the reader might see them for the first time, as "stable" is kind
> of ambiguous, which I wanted to avoid somehow.

In the latest patch (
https://lore.kernel.org/linux-doc/652ee20eb36228f5d7ca842299faa4cb472feedb.1616181657.git.li...@leemhuis.info/
) I removed most of the quoting. I didn't touch other parts of the file
for now. Waiting for an option on this and then will address it in a
septate patch in one go.

> Which brings me to another, but related issue. That patch could also fix
> an inconsistency I recently noticed: how to spell panic, oops, bug,
> warning? I sometimes quoted them  because in kernel context they have
> special meaning, as a BUG() is not some random bug... And is it Oops or
> oops (I recently noticed I used both spellings, but I found both when I
> grepped Documentation/)? Here are some options:
> 
> 1) panic, oops, bug, warning
> 2a) 'panic', 'oops', 'bug', 'warning',
> 2b) *panic*, *oops*, *bug*, *warning*,
> 3) panic, Oops, BUG, WARNING,
> 4) panic, Oops, BUG(), WARN()
> 
> The problem there is similar with the term 'stable': the words bug and
> warning are ambiguous for people that are not familiar with the terms
> used by the kernel community. Putting them in quotes at least give a
> subtle hint like "this term might have a special meaning". It works for
> my subconscious, but I guess won't for many others.
> 
> Nevertheless I'd go option 2a or 2b above: doesn't look to ugly (like 3
> and 4) and avoids being ambiguous (like 1, which I for one don't like at
> all).
> 
> What's your opinion on this? Or do you say "ohh, you are overthinking
> it, just go with option 1!". :-D

Ciao, Thorsten

Re: [PATCH v1, RFC] docs: reporting-issues.rst: tone down 'test vanilla mainline' a little

[Thorsten Leemhuis]

On 15.03.21 21:20, Jonathan Corbet wrote:
> Thorsten Leemhuis  writes:
>> Tell users that reporting bugs with vendor kernels which are only
>> slightly patched can be okay in some situations, but point out there's a
>> risk in doing so.
>>
>> Adjust some related sections to make them compatible and a bit clearer.
>> At the same time make them less daunting: we want users to report bugs,
>> even if they can't test vanilla mainline kernel.
>>
>> Signed-off-by: Thorsten Leemhuis 
>> CC: Randy Dunlap 
>>
>> ---
>> With this I try to get rid of the last remaining parts that have a
>> 'this needs discussion' box that's in the text. I hope I've found a
>> middle ground that everybody can live with.
> 
> For the most part it seems OK to me.

Thx for looking at it!

> I *really* worry, though, that this file is getting so big that few
> people will work their way through it.

Yeah, this is a problem, definitely, but the document was written to
make sure that nobody has to work their way through it, as the "step by
step" guide tells all the important things already – and that guide
(even with this patch and the other one that you looked at yesterday)
should still be shorter (and clearer) then the old "reporting bugs" text
(I hope, I didn't verify...).

>  Anything that could be done to
> make it more concise going forward would be more than welcome.

Yeah, will think about it, especially WRT to the other patch you looked
at. Maybe I can come up with something. But no promises, I put a lot of
thought into the problem already.

The real solution for the problem IMHO looks totally different anyway:
provide pre-compiled kernels somewhere that users can install and even
bisect without installing a compiler at all (sure, there is a the
problem with the configuration, but whatever, just pick one and see how
things work out). Would be a fun project I'd really like to work on
sooner or later, but for now I have different priorities...

> [...]
>> +   suspend your efforts for a few days anyway. Whatever version you choose,
>> +   ideally use a 'vanilla' built. Ignoring these advices will dramatically
>> +   increase the risk you report will be rejected or ignored.
> s/built/build/

Argh, thx for pointing it out.

> Also, I would stop quoting terms like "mainline", "stable" and "vanilla"
> throughout.  It makes the reading experience a bit stranger without
> (IMO) adding anything.

Yeah, let me provide a patch to reduce the quoting. If it's okay for you
I'd like to leave the quotes in the section that round about explains
the terms mainline, stable, and longterm. I think it's wise there to
point out that these are terms that have a special meaning in kernel
context. That's why I quoted them in a lot of places – especially those
where the reader might see them for the first time, as "stable" is kind
of ambiguous, which I wanted to avoid somehow.

Which brings me to another, but related issue. That patch could also fix
an inconsistency I recently noticed: how to spell panic, oops, bug,
warning? I sometimes quoted them  because in kernel context they have
special meaning, as a BUG() is not some random bug... And is it Oops or
oops (I recently noticed I used both spellings, but I found both when I
grepped Documentation/)? Here are some options:

1) panic, oops, bug, warning
2a) 'panic', 'oops', 'bug', 'warning',
2b) *panic*, *oops*, *bug*, *warning*,
3) panic, Oops, BUG, WARNING,
4) panic, Oops, BUG(), WARN()

The problem there is similar with the term 'stable': the words bug and
warning are ambiguous for people that are not familiar with the terms
used by the kernel community. Putting them in quotes at least give a
subtle hint like "this term might have a special meaning". It works for
my subconscious, but I guess won't for many others.

Nevertheless I'd go option 2a or 2b above: doesn't look to ugly (like 3
and 4) and avoids being ambiguous (like 1, which I for one don't like at
all).

What's your opinion on this? Or do you say "ohh, you are overthinking
it, just go with option 1!". :-D

Ciao, Thorsten

Re: [PATCH v1, RFC] docs: reporting-issues.rst: tone down 'test vanilla mainline' a little

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> Tell users that reporting bugs with vendor kernels which are only
> slightly patched can be okay in some situations, but point out there's a
> risk in doing so.
>
> Adjust some related sections to make them compatible and a bit clearer.
> At the same time make them less daunting: we want users to report bugs,
> even if they can't test vanilla mainline kernel.
>
> Signed-off-by: Thorsten Leemhuis 
> CC: Randy Dunlap 
>
> ---
> With this I try to get rid of the last remaining parts that have a
> 'this needs discussion' box that's in the text. I hope I've found a
> middle ground that everybody can live with.

For the most part it seems OK to me.

I *really* worry, though, that this file is getting so big that few
people will work their way through it.  Anything that could be done to
make it more concise going forward would be more than welcome.

One other thing down below...

> v1, RFC
> * this version
> ---
>  .../admin-guide/reporting-issues.rst  | 273 ++
>  1 file changed, 149 insertions(+), 124 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst 
> b/Documentation/admin-guide/reporting-issues.rst
> index 18b1280f7abf..a475e014f9ca 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -94,10 +94,11 @@ early if an issue that looks like a Linux kernel problem 
> is actually caused by
>  something else. These steps thus help to ensure the time you invest in this
>  process won't feel wasted in the end:
>  
> - * Stop reading this document and report the problem to your vendor instead,
> -   unless you are running the latest mainline kernel already or are willing 
> to
> -   install it. This kernel must not be modified or enhanced in any way, and
> -   thus be considered 'vanilla'.
> + * Are you facing an issue with a Linux kernel a hardware or software vendor
> +   provided? Then in almost all cases you are better off to stop reading this
> +   document and reporting the issue to your vendor instead, unless you are
> +   willing to install the latest Linux version yourself. Be aware the latter
> +   will often be needed anyway to hunt down and fix issues.
>  
>   * See if the issue you are dealing with qualifies as regression, security
> issue, or a really severe problem: those are 'issues of high priority' 
> that
> @@ -134,12 +135,14 @@ process won't feel wasted in the end:
>  
>  After these preparations you'll now enter the main part:
>  
> - * Install the latest Linux mainline kernel: that's where all issues get
> -   fixed first, because it's the version line the kernel developers mainly
> -   care about. Testing and reporting with the latest Linux stable kernel can
> -   be an acceptable alternative in some situations, for example during the
> -   merge window; but during that period you might want to suspend your 
> efforts
> -   till its end anyway.
> + * Unless you are already running the latest 'mainline' Linux kernel, better
> +   go and install it for the reporting process. Testing and reporting with
> +   the latest 'stable' Linux can be an acceptable alternative in some
> +   situations; during the merge window that actually might be even the best
> +   approach, but in that development phase it can be an even better idea to
> +   suspend your efforts for a few days anyway. Whatever version you choose,
> +   ideally use a 'vanilla' built. Ignoring these advices will dramatically
> +   increase the risk you report will be rejected or ignored.

s/built/build/

Also, I would stop quoting terms like "mainline", "stable" and "vanilla"
throughout.  It makes the reading experience a bit stranger without
(IMO) adding anything.

Thanks,

jon

[PATCH v1, RFC] docs: reporting-issues.rst: tone down 'test vanilla mainline' a little

[Thorsten Leemhuis]

Tell users that reporting bugs with vendor kernels which are only
slightly patched can be okay in some situations, but point out there's a
risk in doing so.

Adjust some related sections to make them compatible and a bit clearer.
At the same time make them less daunting: we want users to report bugs,
even if they can't test vanilla mainline kernel.

Signed-off-by: Thorsten Leemhuis 
CC: Randy Dunlap 

---
With this I try to get rid of the last remaining parts that have a
'this needs discussion' box that's in the text. I hope I've found a
middle ground that everybody can live with.

v1, RFC
* this version
---
 .../admin-guide/reporting-issues.rst  | 273 ++
 1 file changed, 149 insertions(+), 124 deletions(-)

diff --git a/Documentation/admin-guide/reporting-issues.rst 
b/Documentation/admin-guide/reporting-issues.rst
index 18b1280f7abf..a475e014f9ca 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -94,10 +94,11 @@ early if an issue that looks like a Linux kernel problem is 
actually caused by
 something else. These steps thus help to ensure the time you invest in this
 process won't feel wasted in the end:
 
- * Stop reading this document and report the problem to your vendor instead,
-   unless you are running the latest mainline kernel already or are willing to
-   install it. This kernel must not be modified or enhanced in any way, and
-   thus be considered 'vanilla'.
+ * Are you facing an issue with a Linux kernel a hardware or software vendor
+   provided? Then in almost all cases you are better off to stop reading this
+   document and reporting the issue to your vendor instead, unless you are
+   willing to install the latest Linux version yourself. Be aware the latter
+   will often be needed anyway to hunt down and fix issues.
 
  * See if the issue you are dealing with qualifies as regression, security
issue, or a really severe problem: those are 'issues of high priority' that
@@ -134,12 +135,14 @@ process won't feel wasted in the end:
 
 After these preparations you'll now enter the main part:
 
- * Install the latest Linux mainline kernel: that's where all issues get
-   fixed first, because it's the version line the kernel developers mainly
-   care about. Testing and reporting with the latest Linux stable kernel can
-   be an acceptable alternative in some situations, for example during the
-   merge window; but during that period you might want to suspend your efforts
-   till its end anyway.
+ * Unless you are already running the latest 'mainline' Linux kernel, better
+   go and install it for the reporting process. Testing and reporting with
+   the latest 'stable' Linux can be an acceptable alternative in some
+   situations; during the merge window that actually might be even the best
+   approach, but in that development phase it can be an even better idea to
+   suspend your efforts for a few days anyway. Whatever version you choose,
+   ideally use a 'vanilla' built. Ignoring these advices will dramatically
+   increase the risk you report will be rejected or ignored.
 
  * Ensure the kernel you just installed does not 'taint' itself when
running.
@@ -276,55 +279,54 @@ issues to the Linux kernel developers.
 Make sure you're using the upstream Linux kernel
 
 
-   *Stop reading this document and report the problem to your vendor instead,
-   unless you are running the latest mainline kernel already or are willing to
-   install it. This kernel must not be modified or enhanced in any way, and
-   thus be considered 'vanilla'.*
+   *Are you facing an issue with a Linux kernel a hardware or software vendor
+   provided? Then in almost all cases you are better off to stop reading this
+   document and reporting the issue to your vendor instead, unless you are
+   willing to install the latest Linux version yourself. Be aware the latter
+   will often be needed anyway to hunt down and fix issues.*
 
 Like most programmers, Linux kernel developers don't like to spend time dealing
-with reports for issues that don't even happen with the source code they
-maintain: it's just a waste everybody's time, yours included. That's why you
-later will have to test your issue with the latest 'vanilla' kernel: a kernel
-that was build using the Linux sources taken straight from `kernel.org
-`_ and not modified or enhanced in any way.
-
-Almost all kernels used in devices (Computers, Laptops, Smartphones, Routers,
-???) and most kernels shipped by Linux distributors are ancient from the point 
of
-kernel development and heavily modified. They thus do not qualify for reporting
-an issue to the Linux kernel developers: the issue you face with such a kernel
-might be fixed already or caused by the changes or additions, even if they look
-small or totally unrelated. That's why issues with such kernels need to be
-reported to the vendor that