Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Thorsten Leemhuis]

Am 12.11.20 um 04:33 schrieb Randy Dunlap:

On 11/11/20 7:24 AM, Thorsten Leemhuis wrote:

Am 03.10.20 um 09:27 schrieb Thorsten Leemhuis:

Am 02.10.20 um 04:32 schrieb Randy Dunlap:

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote: […]

> […]

Sorry for the mail with those overly long lines, seems Thunderbird does 
not behave as it used to (or I did something stupid) :-/



I'm preparing to send v2 and was a bit unhappy with this and
another section when seeing it again after weeks. In the end I
reshuffled and rewrote significant parts of it, see below.

[…]
If you can not reproduce the issue with the mainline kernel,
consider sticking with it; if you'd like to use an older version
line and want to see it fixed there, first make sure it's still
supported. Install its latest release as vanilla kernel. If you
cannot reproduce the issue there, try to find the commit that fixed
it in mainline or any discussion preceding it: those will often
mention if backporting is planed or considered impassable. If
backporting was not discussed, ask if it's in the cards. In case
you don't find

impossible.  ??


Hmmm, I didn't won't to use "impossible" as it often is possible, but 
considered to hard/to much work. But I guess my dict sent me the wrong way.


I'll guess I'll switch to "considered too complex"


any commits or a preceding discussion, see the Linux-stable mailing
list archives for existing reports, as it might be a regression
specific to the version line. If it is, it round about needs to be
reported like a problem in mainline (including the bisection).

maybe:  it still needs to be reported like


Went with:

If it is, report it like you would report a problem in mainline 
(including the bisection).



If you reached this point without a solution, ask for advice one
the subsystem's mailing list. ```

Otherwise it looks good to me.


Many thanks for looking at it, much appreciated!

Ciao, Thorsten

Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Randy Dunlap]

On 11/11/20 7:24 AM, Thorsten Leemhuis wrote:
> Am 03.10.20 um 09:27 schrieb Thorsten Leemhuis:
>> Randy, many thanks for looking through this, you feedback is much
>> appreciated! 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 04:32 schrieb Randy Dunlap:
>>> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
>>> […]
 +`_
 +how developers of that particular area expect to be told about issues; 
 note,
>>>     for how
>>> ?
>> Not sure myself, but I guess you're right and thus followed your advice :-D
> 
> I'm preparing to send v2 and was a bit unhappy with this and another section 
> when seeing it again after weeks. In the end I reshuffled and rewrote 
> significant parts of it, see below.
> 
> Randy, would be great if you could take another look, but no pressure: just 
> ignore it, if you lack the time or energy.
> 
> ```
> The short guide (aka TL;DR)
> ===
> 
> If you're facing multiple issues with the Linux kernel at once, report each 
> separately to its developers. Try your best guess which kernel part might be 
> causing the issue. Check the :ref:`MAINTAINERS ` file for how 
> its developers expect to be told about issues. Note, it's rarely 
> `bugzilla.kernel.org `_, as in almost all cases 
> the report needs to be sent by email!
> 
> Check the destination thoroughly for existing reports; also search the LKML 
> archives and the web. Join existing discussion if you find matches. If you 
> don't find any, install `the latest Linux mainline kernel 
> `_. Make sure it's vanilla, thus is not patched or using 
> add-on kernel modules. Also ensure the kernel is running in a healthy 
> environment and is not already tainted before the issue occurs.
> 
> If you can reproduce your issue with the mainline kernel, send a report to 
> the destination you determined earlier. Make sure it includes all relevant 
> information, which in case of a regression should mention the change that's 
> causing it which can often can be found with a bisection. Also ensure the 
> report reaches all people that need to know about it, for example the 
> security team, the stable maintainers or the developers of the patch that 
> causes a regression. Once the report it out, answer any questions that might 
> be raised and help where you can. That includes keeping the ball rolling: 
> every time a new rc1 mainline kernel is released, check if the issue is still 
> happening there and attach a status update to your initial report.
> 
> If you can not reproduce the issue with the mainline kernel, consider 
> sticking with it; if you'd like to use an older version line and want to see 
> it fixed there, first make sure it's still supported. Install its latest 
> release as vanilla kernel. If you cannot reproduce the issue there, try to 
> find the commit that fixed it in mainline or any discussion preceding it: 
> those will often mention if backporting is planed or considered impassable. 
> If backporting was not discussed, ask if it's in the cards. In case you don't 
> find

   impossible.  ??

 any commits or a preceding discussion, see the Linux-stable mailing list 
archives for existing reports, as it might be a regression specific to the 
version line. If it is, it round about needs to be reported like a problem in 
mainline (including the bisection).

 maybe:  it still needs to be reported like

> 
> If you reached this point without a solution, ask for advice one the 
> subsystem's mailing list.
> ```

Otherwise it looks good to me.

thanks.
-- 
~Randy

Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Thorsten Leemhuis]

Am 03.10.20 um 09:27 schrieb Thorsten Leemhuis:

Randy, many thanks for looking through this, you feedback is much
appreciated! 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 04:32 schrieb Randy Dunlap:

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
[…]

+`_
+how developers of that particular area expect to be told about issues; note,

for how
?

Not sure myself, but I guess you're right and thus followed your advice :-D


I'm preparing to send v2 and was a bit unhappy with this and another 
section when seeing it again after weeks. In the end I reshuffled and 
rewrote significant parts of it, see below.


Randy, would be great if you could take another look, but no pressure: 
just ignore it, if you lack the time or energy.


```
The short guide (aka TL;DR)
===

If you're facing multiple issues with the Linux kernel at once, report 
each separately to its developers. Try your best guess which kernel part 
might be causing the issue. Check the :ref:`MAINTAINERS ` 
file for how its developers expect to be told about issues. Note, it's 
rarely `bugzilla.kernel.org `_, as in 
almost all cases the report needs to be sent by email!


Check the destination thoroughly for existing reports; also search the 
LKML archives and the web. Join existing discussion if you find matches. 
If you don't find any, install `the latest Linux mainline kernel 
`_. Make sure it's vanilla, thus is not patched or 
using add-on kernel modules. Also ensure the kernel is running in a 
healthy environment and is not already tainted before the issue occurs.


If you can reproduce your issue with the mainline kernel, send a report 
to the destination you determined earlier. Make sure it includes all 
relevant information, which in case of a regression should mention the 
change that's causing it which can often can be found with a bisection. 
Also ensure the report reaches all people that need to know about it, 
for example the security team, the stable maintainers or the developers 
of the patch that causes a regression. Once the report it out, answer 
any questions that might be raised and help where you can. That includes 
keeping the ball rolling: every time a new rc1 mainline kernel is 
released, check if the issue is still happening there and attach a 
status update to your initial report.


If you can not reproduce the issue with the mainline kernel, consider 
sticking with it; if you'd like to use an older version line and want to 
see it fixed there, first make sure it's still supported. Install its 
latest release as vanilla kernel. If you cannot reproduce the issue 
there, try to find the commit that fixed it in mainline or any 
discussion preceding it: those will often mention if backporting is 
planed or considered impassable. If backporting was not discussed, ask 
if it's in the cards. In case you don't find any commits or a preceding 
discussion, see the Linux-stable mailing list archives for existing 
reports, as it might be a regression specific to the version line. If it 
is, it round about needs to be reported like a problem in mainline 
(including the bisection).


If you reached this point without a solution, ask for advice one the 
subsystem's mailing list.

```

Ciao, Thorsten

Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Thorsten Leemhuis]

Randy, many thanks for looking through this, you feedback is much
appreciated! 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 04:32 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> […]
>> +`_
>> +how developers of that particular area expect to be told about issues; note,
>for how
> ?

Not sure myself, but I guess you're right and thus followed your advice :-D

> […]
>> +Make sure to use a vanilla kernel and avert any add-on kernel modules 
>> externally
>> +developed; also ensure the kernel is running in a healthy environment and 
>> does
>> +not 'taint' itself before the issue occurs. If you can reproduce it, write a
> 
> I don't care for "does not 'taint' itself". How about
>  and 
> is not
>already tainted before the issue occurs.

Hmmm, what I wanted to bring across: the kernel is not tainted when it
arrives, it taints itself after it was started. You suggestion removes
that intention, but now that I read my text again I notice it wasn't
really good at it either. Ohh well, I guess I go with your suggestion,
as it seems bringing that point over it asking for too much here.

> […]
>> +You can't reproduce an issue with mainline you want to see fixed in older
>> +version lines? Then make sure the line you care about still gets support.
>> +Install its latest release as vanilla kernel. If you can reproduce the issue
> 
> Is "vanilla" well understood?

I'd say for the TLDR using it without and explanation is fine. But the
main section didn't prominently mention it, that why I added the first
step slightly and added this:

This kernel must not be modified or enhanced in any way and thus be
'vanilla'.

Ciao, Thorsten

Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Get straight to the point in a few paragraphs instead of forcing users
> to read quite a bit of text, like the old approach did.
> 
> All normally needed fits into the first two paragraphs. The third is
> dedicated to issues only happening in stable and longterm kernels, as
> things otherwise get hard to follow. At the end explicitly spell out
> that some issues need to be handled slightly different.
> 
> This TLDR naturally leaves lots of details out. But it will be good
> enough in some situations, for example for users that recently reported
> an issue or are familiar with reporting issues to FLOSS projects.
> 
> Signed-off-by: Thorsten Leemhuis 
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 43 
>  1 file changed, 43 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst 
> b/Documentation/admin-guide/reporting-bugs.rst
> index 4bbb9132782b..7bde6f32ff72 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -10,6 +10,49 @@ Reporting bugs
>  .. inconsistent/not make sense before all patches of the rewrite got applied.
>  .. 
> ###
>  
> +
> +The short guide (aka TL;DR)
> +===
> +
> +This is how you report issues with the Linux kernel to its developers:
> +
> +If you deal with multiple issues at once, process each of them separately. 
> Try
> +your best guess which area of the kernel might be responsible for your issue.
> +Check the `MAINTAINERS file
> +`_
> +how developers of that particular area expect to be told about issues; note,

   for how
?

> +it's rarely `bugzilla.kernel.org `_, as most
> +subsystems expect reports by mail sent to their maintainers and their public
> +mailing list!
> +
> +Check the archives of the determined destination thoroughly for existing
> +reports; also search the LKML archives and the internet as a whole. If you 
> can't
> +find any, install the `latest Linux mainline version `_.
> +Make sure to use a vanilla kernel and avert any add-on kernel modules 
> externally
> +developed; also ensure the kernel is running in a healthy environment and 
> does
> +not 'taint' itself before the issue occurs. If you can reproduce it, write a

I don't care for "does not 'taint' itself". How about
 and is 
not
   already tainted before the issue occurs.

> +report to the destination you determined earlier. Afterwards keep the ball
> +rolling by proactive testing, a status update now and then, and helping where
> +you can.
> +
> +You can't reproduce an issue with mainline you want to see fixed in older
> +version lines? Then make sure the line you care about still gets support.
> +Install its latest release as vanilla kernel. If you can reproduce the issue

Is "vanilla" well understood?

> +there, try to find the commit that fixed it in mainline or any discussion
> +preceding it: those will often mention if backporting is planed or 
> impossible;
> +if not, ask for it. In case you don't find anything, check if it's a 
> regression
> +specific to the version line that need to be bisected and report just like a

that needs

> +problem in mainline with the stable mailing list CCed. If you reached this 
> point
> +without a solution, ask for advice by mailing the subsystem maintainer with 
> the
> +subsystem and stable mailing list in CC.
> +
> +If you deal with a regression, bisect it to find the culprit and CC or 
> forward
> +your report to its developers.
> +
> +Security issues are typically best report privately; also CC the security 
> team

  reported

> +or forward your report there.
> +
> +
>  .. 
> 
>  .. Temporary marker added while this document is rewritten. Sections above
>  .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.
> 


-- 
~Randy

[RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Thorsten Leemhuis]

Get straight to the point in a few paragraphs instead of forcing users
to read quite a bit of text, like the old approach did.

All normally needed fits into the first two paragraphs. The third is
dedicated to issues only happening in stable and longterm kernels, as
things otherwise get hard to follow. At the end explicitly spell out
that some issues need to be handled slightly different.

This TLDR naturally leaves lots of details out. But it will be good
enough in some situations, for example for users that recently reported
an issue or are familiar with reporting issues to FLOSS projects.

Signed-off-by: Thorsten Leemhuis 
---
 Documentation/admin-guide/reporting-bugs.rst | 43 
 1 file changed, 43 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst 
b/Documentation/admin-guide/reporting-bugs.rst
index 4bbb9132782b..7bde6f32ff72 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -10,6 +10,49 @@ Reporting bugs
 .. inconsistent/not make sense before all patches of the rewrite got applied.
 .. ###
 
+
+The short guide (aka TL;DR)
+===
+
+This is how you report issues with the Linux kernel to its developers:
+
+If you deal with multiple issues at once, process each of them separately. Try
+your best guess which area of the kernel might be responsible for your issue.
+Check the `MAINTAINERS file
+`_
+how developers of that particular area expect to be told about issues; note,
+it's rarely `bugzilla.kernel.org `_, as most
+subsystems expect reports by mail sent to their maintainers and their public
+mailing list!
+
+Check the archives of the determined destination thoroughly for existing
+reports; also search the LKML archives and the internet as a whole. If you 
can't
+find any, install the `latest Linux mainline version `_.
+Make sure to use a vanilla kernel and avert any add-on kernel modules 
externally
+developed; also ensure the kernel is running in a healthy environment and does
+not 'taint' itself before the issue occurs. If you can reproduce it, write a
+report to the destination you determined earlier. Afterwards keep the ball
+rolling by proactive testing, a status update now and then, and helping where
+you can.
+
+You can't reproduce an issue with mainline you want to see fixed in older
+version lines? Then make sure the line you care about still gets support.
+Install its latest release as vanilla kernel. If you can reproduce the issue
+there, try to find the commit that fixed it in mainline or any discussion
+preceding it: those will often mention if backporting is planed or impossible;
+if not, ask for it. In case you don't find anything, check if it's a regression
+specific to the version line that need to be bisected and report just like a
+problem in mainline with the stable mailing list CCed. If you reached this 
point
+without a solution, ask for advice by mailing the subsystem maintainer with the
+subsystem and stable mailing list in CC.
+
+If you deal with a regression, bisect it to find the culprit and CC or forward
+your report to its developers.
+
+Security issues are typically best report privately; also CC the security team
+or forward your report there.
+
+
 .. 
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.
-- 
2.26.2