Re: [1/5] reporting-issues: header and TLDR

[Thorsten Leemhuis]

On 30.03.21 07:59, Greg KH wrote:
> On Mon, Mar 29, 2021 at 04:44:21PM -0600, Jonathan Corbet wrote:
>> Thorsten Leemhuis  writes:
>>
>>> FWIW, on another channel someone mentioned the process in the TLDR is
>>> quite complicated when it comes to regressions in stable and longterm
>>> kernels. I looked at the text and it seemed like a valid complaint, esp.
>>> as those regressions are something we really care about.
>>>
>>> To solve this properly I sadly had to shake up the text in this section
>>> completely and rewrite parts of it. Find the result below. I'm quite
>>> happy with it, as it afaics is more straight forward and easier to
>>> understand. And it matches the step-by-step guide better. And the best
>>> thing: it's a bit shorter than the old TLDR.
>>
>> I think this is much improved - concise is good! :)

Yeah, I was kinda unhappy with the old version myself and glad that
something made be revisit this...

>>  I really just have one little comment...

Great!

>>> I'll wait a day or two and then will send it through the regular review
>>> together with a few small other fixes that piled up for the text, just
>>> wanted to add it here for completeness.
>>>
>>> ---
>>> The short guide (aka TL;DR)
>>> ===
>>>
>>> Are you facing a regression with vanilla kernels from the same stable or
>>> longterm series? One still supported? Then search the `LKML
>>> `_ and the `Linux stable mailing list
>>> _` archives for matching reports to
>>> join. If you don't find any, install `the latest release from that
>>> series `_. If it still shows the issue, report it
>>> to the stable mailing list and the stable maintainers.
>>
>> If we really want this to be a short guide that gets people to the
>> answer quickly, we might as well put the addresses to report to right
>> here rather than making people search for them.
> 
> "sta...@vger.kernel.org" is good to use here, no need to also cc: any
> individuals for this type of thing.

Ahh, good to know, will change this accordingly. Will also change other
places in the text where this comes up.

Thx for the feedback! Ciao, Thorsten

Re: [1/5] reporting-issues: header and TLDR

[Greg KH]

On Mon, Mar 29, 2021 at 04:44:21PM -0600, Jonathan Corbet wrote:
> Thorsten Leemhuis  writes:
> 
> > FWIW, on another channel someone mentioned the process in the TLDR is
> > quite complicated when it comes to regressions in stable and longterm
> > kernels. I looked at the text and it seemed like a valid complaint, esp.
> > as those regressions are something we really care about.
> >
> > To solve this properly I sadly had to shake up the text in this section
> > completely and rewrite parts of it. Find the result below. I'm quite
> > happy with it, as it afaics is more straight forward and easier to
> > understand. And it matches the step-by-step guide better. And the best
> > thing: it's a bit shorter than the old TLDR.
> 
> I think this is much improved - concise is good! :)  I really just have
> one little comment...
> 
> > I'll wait a day or two and then will send it through the regular review
> > together with a few small other fixes that piled up for the text, just
> > wanted to add it here for completeness.
> >
> > ---
> > The short guide (aka TL;DR)
> > ===
> >
> > Are you facing a regression with vanilla kernels from the same stable or
> > longterm series? One still supported? Then search the `LKML
> > `_ and the `Linux stable mailing list
> > _` archives for matching reports to
> > join. If you don't find any, install `the latest release from that
> > series `_. If it still shows the issue, report it
> > to the stable mailing list and the stable maintainers.
> 
> If we really want this to be a short guide that gets people to the
> answer quickly, we might as well put the addresses to report to right
> here rather than making people search for them.

"sta...@vger.kernel.org" is good to use here, no need to also cc: any
individuals for this type of thing.

thanks,

greg k-h

Re: [1/5] reporting-issues: header and TLDR

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> FWIW, on another channel someone mentioned the process in the TLDR is
> quite complicated when it comes to regressions in stable and longterm
> kernels. I looked at the text and it seemed like a valid complaint, esp.
> as those regressions are something we really care about.
>
> To solve this properly I sadly had to shake up the text in this section
> completely and rewrite parts of it. Find the result below. I'm quite
> happy with it, as it afaics is more straight forward and easier to
> understand. And it matches the step-by-step guide better. And the best
> thing: it's a bit shorter than the old TLDR.

I think this is much improved - concise is good! :)  I really just have
one little comment...

> I'll wait a day or two and then will send it through the regular review
> together with a few small other fixes that piled up for the text, just
> wanted to add it here for completeness.
>
> ---
> The short guide (aka TL;DR)
> ===
>
> Are you facing a regression with vanilla kernels from the same stable or
> longterm series? One still supported? Then search the `LKML
> `_ and the `Linux stable mailing list
> _` archives for matching reports to
> join. If you don't find any, install `the latest release from that
> series `_. If it still shows the issue, report it
> to the stable mailing list and the stable maintainers.

If we really want this to be a short guide that gets people to the
answer quickly, we might as well put the addresses to report to right
here rather than making people search for them.

Thanks,

jon

Re: [1/5] reporting-issues: header and TLDR

[Greg KH]

On Sun, Mar 28, 2021 at 11:23:30AM +0200, Thorsten Leemhuis wrote:
> On 26.03.21 07:15, Thorsten Leemhuis wrote:
> > On 26.03.21 07:13, Thorsten Leemhuis wrote:
> >>
> >> Lo! Since a few months mainline in
> >> Documentation/admin-guide/reporting-issues.rst contains a text written
> >> to obsolete the good old reporting-bugs text. For now, the new document
> >> still contains a warning at the top that basically says "this is WIP".
> >> But I'd like to remove that warning and delete reporting-bugs.rst in the
> >> next merge window to make reporting-issues.rst fully official. With this
> >> mail I want to give everyone a chance to take a look at the text and
> >> speak up if you don't want me to move ahead for now.
> >>
> >> For easier review I'll post the text of reporting-issues.rst in reply to
> >> this mail. I'll do that in a few chunks, as if this was a cover letter
> >> for a patch-set. 
> > Here we go:
> > [...]
> > Reporting issues
> > 
> > 
> > The short guide (aka TL;DR)
> > ===
> > 
> > [...]
> 
> 
> FWIW, on another channel someone mentioned the process in the TLDR is
> quite complicated when it comes to regressions in stable and longterm
> kernels. I looked at the text and it seemed like a valid complaint, esp.
> as those regressions are something we really care about.
> 
> To solve this properly I sadly had to shake up the text in this section
> completely and rewrite parts of it. Find the result below. I'm quite
> happy with it, as it afaics is more straight forward and easier to
> understand. And it matches the step-by-step guide better. And the best
> thing: it's a bit shorter than the old TLDR.
> 
> I'll wait a day or two and then will send it through the regular review
> together with a few small other fixes that piled up for the text, just
> wanted to add it here for completeness.
> 
> ---
> The short guide (aka TL;DR)
> ===
> 
> Are you facing a regression with vanilla kernels from the same stable or
> longterm series? One still supported? Then search the `LKML
> `_ and the `Linux stable mailing list
> _` archives for matching reports to
> join. If you don't find any, install `the latest release from that
> series `_. If it still shows the issue, report it
> to the stable mailing list and the stable maintainers.
> 
> In all other cases 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 problems, which most of the
> time will be by email with a mailing list in CC. Check the destination's
> archives for matching reports; search the `LKML
> `_ and the web, too. If you don't find
> any to join, install `the latest mainline kernel
> `_. If the issue is present there, send a report.
> 
> If you would like to see the issue also fixed in a still supported
> stable or longterm series, install its latest release. If it shows the
> problem, search for the change that fixed it in mainline and check if
> backporting is in the works or was discarded; if it's neither, ask those
> who handled the change for it.
> 
> **General remarks**: When installing and testing a kernel as outlined
> above, ensure it's vanilla (IOW: not patched and not using add-on
> modules). Also make sure it's built and running in a healthy environment
> and not already tainted before the issue occurs.
> 
> While writing your report, include all information relevant to the
> issue, like the kernel and the distro used. In case of a regression try
> to include the commit-id of the change causing it, which a bisection can
> find. If you're facing multiple issues with the Linux kernel at once,
> report each separately.
> 
> Once the report is out, answer any questions that come up and help where
> you can. That includes keeping the ball rolling by occasionally
> retesting with newer releases and sending a status update afterwards.
> 
> ---

The above looks good to me, thanks for doing this work.

greg k-h

Re: [1/5] reporting-issues: header and TLDR

[Thorsten Leemhuis]

On 26.03.21 07:15, Thorsten Leemhuis wrote:
> On 26.03.21 07:13, Thorsten Leemhuis wrote:
>>
>> Lo! Since a few months mainline in
>> Documentation/admin-guide/reporting-issues.rst contains a text written
>> to obsolete the good old reporting-bugs text. For now, the new document
>> still contains a warning at the top that basically says "this is WIP".
>> But I'd like to remove that warning and delete reporting-bugs.rst in the
>> next merge window to make reporting-issues.rst fully official. With this
>> mail I want to give everyone a chance to take a look at the text and
>> speak up if you don't want me to move ahead for now.
>>
>> For easier review I'll post the text of reporting-issues.rst in reply to
>> this mail. I'll do that in a few chunks, as if this was a cover letter
>> for a patch-set. 
> Here we go:
> [...]
> Reporting issues
> 
> 
> The short guide (aka TL;DR)
> ===
> 
> [...]


FWIW, on another channel someone mentioned the process in the TLDR is
quite complicated when it comes to regressions in stable and longterm
kernels. I looked at the text and it seemed like a valid complaint, esp.
as those regressions are something we really care about.

To solve this properly I sadly had to shake up the text in this section
completely and rewrite parts of it. Find the result below. I'm quite
happy with it, as it afaics is more straight forward and easier to
understand. And it matches the step-by-step guide better. And the best
thing: it's a bit shorter than the old TLDR.

I'll wait a day or two and then will send it through the regular review
together with a few small other fixes that piled up for the text, just
wanted to add it here for completeness.

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

Are you facing a regression with vanilla kernels from the same stable or
longterm series? One still supported? Then search the `LKML
`_ and the `Linux stable mailing list
_` archives for matching reports to
join. If you don't find any, install `the latest release from that
series `_. If it still shows the issue, report it
to the stable mailing list and the stable maintainers.

In all other cases 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 problems, which most of the
time will be by email with a mailing list in CC. Check the destination's
archives for matching reports; search the `LKML
`_ and the web, too. If you don't find
any to join, install `the latest mainline kernel
`_. If the issue is present there, send a report.

If you would like to see the issue also fixed in a still supported
stable or longterm series, install its latest release. If it shows the
problem, search for the change that fixed it in mainline and check if
backporting is in the works or was discarded; if it's neither, ask those
who handled the change for it.

**General remarks**: When installing and testing a kernel as outlined
above, ensure it's vanilla (IOW: not patched and not using add-on
modules). Also make sure it's built and running in a healthy environment
and not already tainted before the issue occurs.

While writing your report, include all information relevant to the
issue, like the kernel and the distro used. In case of a regression try
to include the commit-id of the change causing it, which a bisection can
find. If you're facing multiple issues with the Linux kernel at once,
report each separately.

Once the report is out, answer any questions that come up and help where
you can. That includes keeping the ball rolling by occasionally
retesting with newer releases and sending a status update afterwards.

---


Ciao, Thorsten

Re: [Ksummit-discuss] [1/5] reporting-issues: header and TLDR

[Thorsten Leemhuis]

On 26.03.21 07:23, Guenter Roeck wrote:
> On 3/25/21 11:15 PM, Thorsten Leemhuis wrote:
>> On 26.03.21 07:13, Thorsten Leemhuis wrote:
>
>> mention if backporting is planed or considered too complex. If backporting 
>> was
> planned

ha, of course, thx for pointing it out! Ciao, Thorsten

Re: [Ksummit-discuss] [1/5] reporting-issues: header and TLDR

[Guenter Roeck]

On 3/25/21 11:15 PM, Thorsten Leemhuis wrote:
> On 26.03.21 07:13, Thorsten Leemhuis wrote:
>>

> mention if backporting is planed or considered too complex. If backporting was

planned

[1/5] reporting-issues: header and TLDR

[Thorsten Leemhuis]

On 26.03.21 07:13, Thorsten Leemhuis wrote:
> 
> Lo! Since a few months mainline in
> Documentation/admin-guide/reporting-issues.rst contains a text written
> to obsolete the good old reporting-bugs text. For now, the new document
> still contains a warning at the top that basically says "this is WIP".
> But I'd like to remove that warning and delete reporting-bugs.rst in the
> next merge window to make reporting-issues.rst fully official. With this
> mail I want to give everyone a chance to take a look at the text and
> speak up if you don't want me to move ahead for now.
> 
> For easier review I'll post the text of reporting-issues.rst in reply to
> this mail. I'll do that in a few chunks, as if this was a cover letter
> for a patch-set. 

Here we go:

.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)

..

   If you want to distribute this text under CC-BY-4.0 only, please use 'The

   Linux kernel developers' for author attribution and link this as source:

   
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst

..

   Note: Only the content of this RST file as found in the Linux kernel sources

   is available under CC-BY-4.0, as versions of this text that were processed

   (for example by the kernel's build system) might contain content taken from

   files which use a more restrictive license.





Reporting issues







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 is 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 too complex. 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,

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.