LinuxLists.cc - [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

[permalink] [raw]

Subject: [RFC PATCH v2 14/26] docs: reporting-bugs: make users write notes, one for each issue

Tell users to write some rough notes how to reproduce the issue. They
will need those notes soon once they have to reproduce the issue with a
fresh kernel later in the process. At the same time the notes can serve
as basis for the report later.

While at it point out that each report should focus on one issue, as
that is a good time for it: it will make the notes more straight forward
if the reader deal with multiple issues at once.

Signed-off-by: Thorsten Leemhuis <[email protected]>
---
Documentation/admin-guide/reporting-bugs.rst | 36 +++++++++++++++-----
1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 234731cd0c78..981ddd5a0646 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -659,6 +659,33 @@ should minimize it:
like a kernel regression.

+Document how to reproduce issue
+-------------------------------
+
+ *Write down coarsely how to reproduce the issue. If you deal with multiple
+ issues at once, create separate notes for each of them and make sure they
+ work independently on a freshly booted system. That's needed, as each issue
+ needs to get reported to the kernel developers separately, unless they are
+ strongly entangled.*
+
+If you deal with multiple issues at once, you'll have to report each of them
+separately, as they might be handled by different developers. Describing
+various issues in one report also makes it quite difficult for others to tear
+it apart. Hence, only combine issues in one report if they are very strongly
+entangled.
+
+Additionally, during the reporting process you will have to test if the issue
+happens with other kernel versions. Therefore, it will make your work easier if
+you know exactly how to reproduce an issue quickly on a freshly booted system.
+
+Note: it's often fruitless to report issues that only happened once, as they
+might be caused by a bit flip due to cosmic radiation. That's why you should
+try to rule that out by reproducing the issue before going further. Feel free
+to ignore this advice if you are experienced enough to tell a one-time error
+due to faulty hardware apart from a kernel issue that rarely happens and thus
+is hard to reproduce.
+
+
.. ############################################################################
.. 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.
@@ -681,15 +708,6 @@ How to report Linux kernel bugs
===============================

-Tips for reporting bugs
------------------------
-
-It's REALLY important to report bugs that seem unrelated as separate email
-threads or separate bugzilla entries. If you report several unrelated
-bugs at once, it's difficult for maintainers to tease apart the relevant
-data.
-
-
Gather information
------------------

--
2.28.0

2020-11-12 18:05:48

[permalink] [raw]

Subject: [RFC PATCH v2 04/26] docs: reporting-bugs: step-by-step guide for issues in stable & longterm

Handle stable and longterm kernels in a subsection, as dealing with them
directly in the main part of the step-by-step guide turned out to make
it messy and hard to follow: it looked a bit like code with a large
amount of if-then-else section to handle special cases, which made the
typical flow hard to understand.

Yet again a reference section will later describe each step in more
detail and repeat each step as introduction.

Signed-off-by: Thorsten Leemhuis <[email protected]>
---
Documentation/admin-guide/reporting-bugs.rst | 48 ++++++++++++++++++++
1 file changed, 48 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index a654c54d7dc6..2b48c824d070 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -162,6 +162,54 @@ After these preparations you'll now enter the main part:
help yourself, if you don't get any help or if it's unsatisfying.

+Reporting issues only occurring in older kernel version lines
+-------------------------------------------------------------
+
+This section is for you, if you tried the latest mainline kernel as outlined
+above, but failed to reproduce your issue there; at the same time you want to
+see the issue fixed in older version lines or a vendor kernel that's regularly
+rebased on new stable or longterm releases. If that case follow these steps:
+
+ * Prepare yourself for the possibility that going through the next few steps
+ might not get the issue solved in older releases: the fix might be too big
+ or risky to get backported there.
+
+ * Check if the kernel developers still maintain the Linux kernel version
+ line you care about: go to the front page of kernel.org and make sure it
+ mentions the latest release of the particular version line without an
+ '[EOL]' tag.
+
+ * Check the archives of the Linux stable mailing list for existing reports.
+
+ * Install the latest release from the particular version line as a vanilla
+ kernel. Ensure this kernel is not tainted and still shows the problem, as
+ the issue might have already been fixed there.
+
+ * Search the Linux kernel version control system for the change that fixed
+ the issue in mainline, as its commit message might tell you if the fix is
+ scheduled for backporting already. If you don't find anything that way,
+ search the appropriate mailing lists for posts that discuss such an issue
+ or peer-review possible fixes; then check the discussions if the fix was
+ deemed unsuitable for backporting. If backporting was not considered at
+ all, join the newest discussion, asking if it's in the cards.
+
+ * Check if you're dealing with a regression that was never present in
+ mainline by installing the first release of the version line you care
+ about. If the issue doesn't show up with it, you basically need to report
+ the issue with this version like you would report a problem with mainline
+ (see above). This ideally includes a bisection followed by a search for
+ existing reports on the net; with the help of the subject and the two
+ relevant commit-ids. If that doesn't turn up anything, write the report; CC
+ or forward the report to the stable maintainers, the stable mailing list,
+ and those who authored the change. Include the shortened commit-id if you
+ found the change that causes it.
+
+ * One of the former steps should lead to a solution. If that doesn't work
+ out, ask the maintainers for the subsystem that seems to be causing the
+ issue for advice; CC the mailing list for the particular subsystem as well
+ as the stable mailing list.
+
+
.. ############################################################################
.. 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.28.0

2020-11-12 18:06:58

[permalink] [raw]

Subject: [RFC PATCH v2 07/26] docs: reporting-bugs: let users classify their issue

Explicitly outline that some issues are more important than others and
thus need to be handled differently in some steps that are about to
follow. This makes things explicit and easy to find if you need to look
up what issues actually qualify as "regression" or a "severe problem".

The alternative would have been: explain each of the three types in the
place where it requires special handling for the first time. But that
makes it quite easy to miss and harder to find when you need to look it
up.

Signed-off-by: Thorsten Leemhuis <[email protected]>
---
Documentation/admin-guide/reporting-bugs.rst | 39 ++++++++++++++++++++
1 file changed, 39 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 9122889509de..fdd79d99c18f 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -280,6 +280,45 @@ mainline kernel yourself and reporting the issue as outlined in this document;
just make sure to use really fresh kernel (see below).

+Issue of high priority?
+-----------------------
+
+ *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
+ need special handling in some steps that are about to follow.*
+
+Linus Torvalds and the leading Linux kernel developers want to see some issues
+fixed as soon as possible, hence there are 'issues of high priority' that get
+handled slightly differently in the reporting process. Three type of cases
+qualify: regressions, security issues, and really severe problems.
+
+You deal with a 'regression' if something that worked with an older version of
+the Linux kernel does not work with a newer one or somehow works worse with it.
+It thus is a regression when a WiFi driver that did a fine job with Linux 5.7
+somehow misbehaves with 5.8 or doesn't work at all. It's also a regression if
+an application shows erratic behavior with a newer kernel, which might happen
+due to incompatible changes in the interface between the kernel and the
+userland (like procfs and sysfs). Significantly reduced performance or
+increased power consumption also qualify as regression. But keep in mind: the
+new kernel needs to be built with a configuration that is similar to the one
+from the old kernel (see below how to achieve that). That's because the kernel
+developers sometimes can not avoid incompatibilities when implementing new
+features; but to avoid regressions such features have to be enabled explicitly
+during build time configuration.
+
+What qualifies as security issue is left to your judgment. Consider reading
+:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` before
+proceeding.
+
+An issue is a 'really severe problem' when something totally unacceptably bad
+happens. That's for example the case when a Linux kernel corrupts the data it's
+handling or damages hardware it's running on. You're also dealing with a severe
+issue when the kernel suddenly stops working with an error message ('kernel
+panic') or without any farewell note at all. Note: do not confuse a 'panic' (a
+fatal error where the kernel stop itself) with a 'Oops' (a recoverable error),
+as the kernel remains running after the latter.
+
+
.. ############################################################################
.. 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.28.0

2020-11-13 22:37:02

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

On Thu, 12 Nov 2020 18:58:37 +0100
Thorsten Leemhuis <[email protected]> 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.

As for how to proceed...getting others to review this is going to be a bit
of a challenge. Perhaps the right approach is to just merge the new
document under a new name - reporting-bugs-the-novel.txt 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?

Thanks,

jon

2020-11-13 22:49:23

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

On 11/13/20 2:33 PM, Jonathan Corbet wrote:
> On Thu, 12 Nov 2020 18:58:37 +0100
> Thorsten Leemhuis <[email protected]> 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.
>
> As for how to proceed...getting others to review this is going to be a bit
> of a challenge. Perhaps the right approach is to just merge the new
> document under a new name - reporting-bugs-the-novel.txt 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?

I like that idea.

I don't plan to review the series in detail like I did with v1.

--
~Randy

2020-11-15 13:04:22

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

Am 13.11.20 um 23:33 schrieb Jonathan Corbet:
> On Thu, 12 Nov 2020 18:58:37 +0100
> Thorsten Leemhuis <[email protected]> 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

2020-11-19 00:35:13

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

On Sun, 15 Nov 2020 11:13:52 +0100
Thorsten Leemhuis <[email protected]> wrote:

> > 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.

OK, I have made a *quick* pass through the whole thing and sent a small
number of comments separately. There are things that could be tweaked
(there always will be) but I'm not sure we should worry about those yet.
I would suggest doing this:

- Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
(or some suitable name). I do wonder if it should also move to the
process manual as part of this; not only admins will report bugs.

- Add a comment at the top saying it's a proposed replacement and
soliciting comments. You could also put some of your other questions
into the text for now and see if anybody reacts.

- In a separate patch you could add a comment to the existing document
pointing to the new one as the true source of wisdom.

- Dual licensed CC-SA-4.0 is fine with me. CC-BY is OK if you really
want to do it that way. Either way, though, you'll need to add the
license itself under LICENSES/preferred before it can go into the SPDX
tag.

With that, I'd say let's just merge it and bash on it from there.

Thanks,

jon

2020-11-19 12:34:46

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
> On Sun, 15 Nov 2020 11:13:52 +0100
> Thorsten Leemhuis <[email protected]> wrote:
>
>>> 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.
> OK, I have made a *quick* pass through the whole thing and sent a small
> number of comments separately.

Great, thx, much appreciated.

> There are things that could be tweaked
> (there always will be) but I'm not sure we should worry about those yet.
> I would suggest doing this:
>
> - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
> (or some suitable name).

Maybe just "reporting-issues.rst" or "reporting-issues-wip.rst". The
text talks about issues anyway and rarely uses the word "bug".

> I do wonder if it should also move to the
> process manual as part of this; not only admins will report bugs.

I had wondered about this myself a few weeks ago, but I assumed someone
had good reasons to put it in the admin section.

/me looks closer

Hmmm, now I'm unsure myself where to place it:

* Documentation/admin/ is introduced as "The Linux kernel user’s and
administrator’s guide"
(https://www.kernel.org/doc/html/latest/admin-guide/). So maybe it's the
right place that just uses a directory name that's easily misunderstood :-/

* the process section starts with the words "So you want to be a Linux
kernel developer? Welcome!"
(https://www.kernel.org/doc/html/latest/process/). That might be a bit
intimidating for people that just want to report a bug.

I guess it's best if you decide.

> - Add a comment at the top saying it's a proposed replacement and
> soliciting comments. You could also put some of your other questions
> into the text for now and see if anybody reacts.
>
> - In a separate patch you could add a comment to the existing document
> pointing to the new one as the true source of wisdom.

Will do.

> - Dual licensed CC-SA-4.0 is fine with me. CC-BY is OK if you really
> want to do it that way.

I'm unsure and would appreciate options from others here.

Here are some of my thoughts about this:

What do we loose by dual-licensing it under a liberal license like
CC-BY? It afaics makes it a lot more attractive for websites or books
authors to use this text as a base, as they don't need to fear that
"share alike" or the GPL might have consequences on the surroundings.
I'd say that's a good thing for the kernel, as it increases the chances
the texts built upon ours remain close to what we expect on this topic.

That's why I currently think using CC-BY is a good idea.

> Either way, though, you'll need to add the
> license itself under LICENSES/preferred before it can go into the SPDX
> tag.

Agh, yes, of course, will keep it in mind when above point is settled.

Ciao, Thorsten

2020-11-19 16:24:15

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

On 11/19/20 4:29 AM, Thorsten Leemhuis wrote:
> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
>> On Sun, 15 Nov 2020 11:13:52 +0100
>> Thorsten Leemhuis <[email protected]> wrote:
>>
>>>> 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.
>> OK, I have made a *quick* pass through the whole thing and sent a small
>> number of comments separately.
>
> Great, thx, much appreciated.
>
>> There are things that could be tweaked
>> (there always will be) but I'm not sure we should worry about those yet.
>> I would suggest doing this:
>>
>> - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
>> (or some suitable name).
>
> Maybe just "reporting-issues.rst" or "reporting-issues-wip.rst". The text talks about issues anyway and rarely uses the word "bug".
>
>> I do wonder if it should also move to the
>> process manual as part of this; not only admins will report bugs.
>
>
> I had wondered about this myself a few weeks ago, but I assumed someone had good reasons to put it in the admin section.
>
> /me looks closer
>
> Hmmm, now I'm unsure myself where to place it:
>
> * Documentation/admin/ is introduced as "The Linux kernel user’s and administrator’s guide" (https://www.kernel.org/doc/html/latest/admin-guide/). So maybe it's the right place that just uses a directory name that's easily misunderstood :-/
>
> * the process section starts with the words "So you want to be a Linux kernel developer? Welcome!" (https://www.kernel.org/doc/html/latest/process/). That might be a bit intimidating for people that just want to report a bug.
>
> I guess it's best if you decide.
I prefer to leave it in /admin-guide/.

--
~Randy

2020-11-20 10:48:17

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
> On Sun, 15 Nov 2020 11:13:52 +0100
> Thorsten Leemhuis <[email protected]> wrote:

> - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
> (or some suitable name). I do wonder if it should also move to the
> process manual as part of this; not only admins will report bugs.

After a night's sleep and Randy's comment I for now settled on
Documentation/admin-guide/reporting-issues.rst

> - Add a comment at the top saying it's a proposed replacement and
> soliciting comments. [...]
Struggled a bit to find the right words, but I think this should work:

```
.. important::

This document is being prepared to replace
Documentation/admin-guide/reporting-bugs.rst. The main work is done and
you are already free to follow its instructions when reporting issues to
the Linux kernel developers. But keep in mind, below text still needs a
few finishing touches and review. It was merged to the Linux kernel
sources at this stage to make this process easier and increase the
text's visibility.

Any improvements for the text or other feedback is thus very much
welcome. Please send it to 'Thorsten Leemhuis <[email protected]>' and
'Jonathan Corbet <[email protected]>', ideally with 'Linux kernel mailing
list (LKML) <[email protected]>' and the 'Linux Kernel
Documentation List <[email protected]>' in CC.

Areas in the text that still need work or discussion contain a hint
like this which point out the remaining issues; all of them start with
the word "FIXME" to make them easy to find.
```

Randy let me know if you want to be mentioned there, too.

> - In a separate patch you could add a comment to the existing document
> pointing to the new one as the true source of wisdom.

This is what I plan to add:

```
.. note::

Instead of reading below text consider reading this document
instead: Documentation/admin-guide/reporting-issues.rst. It's intended
to replace below text in the near future, as it's easier to grasp and
more straight forward; it also provides way more details and more
accurately describes the steps currently needed when reporting bugs to
the Linux developers.
```

Ciao, Thorsten

2020-11-20 16:30:23

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

On 11/20/20 2:46 AM, Thorsten Leemhuis wrote:
> Any improvements for the text or other feedback is thus very much welcome. Please send it to 'Thorsten Leemhuis <[email protected]>' and 'Jonathan Corbet <[email protected]>', ideally with 'Linux kernel mailing list (LKML) <[email protected]>' and the 'Linux Kernel Documentation List <[email protected]>' in CC.
>
> Areas in the text that still need work or discussion contain a hint like this which point out the remaining issues; all of them start with the word "FIXME" to make them easy to find.
> ```
>
> Randy let me know if you want to be mentioned there, too.

No thanks, I don't need to be mentioned.
I'll see it (unless I can't).

--
~Randy

2020-11-20 22:01:12

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

On Fri, 20 Nov 2020 11:46:07 +0100
Thorsten Leemhuis <[email protected]> wrote:

> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
> > On Sun, 15 Nov 2020 11:13:52 +0100
> > Thorsten Leemhuis <[email protected]> wrote:
>
> > - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
> > (or some suitable name). I do wonder if it should also move to the
> > process manual as part of this; not only admins will report bugs.
>
> After a night's sleep and Randy's comment I for now settled on
> Documentation/admin-guide/reporting-issues.rst

Keeping it in the admin guide is OK. Not sure about the name, though; if
you're really dead set against bugs, maybe reporting-problems.rst?

> > - Add a comment at the top saying it's a proposed replacement and
> > soliciting comments. [...]
> Struggled a bit to find the right words, but I think this should work:
>
> ```
> .. important::
>
> This document is being prepared to replace
> Documentation/admin-guide/reporting-bugs.rst. The main work is done and
> you are already free to follow its instructions when reporting issues to
> the Linux kernel developers. But keep in mind, below text still needs a
> few finishing touches and review. It was merged to the Linux kernel
> sources at this stage to make this process easier and increase the
> text's visibility.
>
> Any improvements for the text or other feedback is thus very much
> welcome. Please send it to 'Thorsten Leemhuis <[email protected]>' and
> 'Jonathan Corbet <[email protected]>', ideally with 'Linux kernel mailing
> list (LKML) <[email protected]>' and the 'Linux Kernel
> Documentation List <[email protected]>' in CC.
>
> Areas in the text that still need work or discussion contain a hint
> like this which point out the remaining issues; all of them start with
> the word "FIXME" to make them easy to find.
> ```

Seems OK.

> > - In a separate patch you could add a comment to the existing document
> > pointing to the new one as the true source of wisdom.
>
> This is what I plan to add:
>
> ```
> .. note::
>
> Instead of reading below text consider reading this document
> instead: Documentation/admin-guide/reporting-issues.rst. It's intended
> to replace below text in the near future, as it's easier to grasp and
> more straight forward; it also provides way more details and more
> accurately describes the steps currently needed when reporting bugs to
> the Linux developers.
> ```

I'd be a bit more straightforward:

This document is obsolete, and will be replaced by
Documentation/admin-guide/$NAME in the near future.

Not sure that more is really needed?

jon

2020-11-20 22:01:52

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

On Thu, 19 Nov 2020 13:29:51 +0100
Thorsten Leemhuis <[email protected]> wrote:

> > - Dual licensed CC-SA-4.0 is fine with me. CC-BY is OK if you really
> > want to do it that way.
>
> I'm unsure and would appreciate options from others here.
>
> Here are some of my thoughts about this:
>
> What do we loose by dual-licensing it under a liberal license like
> CC-BY? It afaics makes it a lot more attractive for websites or books
> authors to use this text as a base, as they don't need to fear that
> "share alike" or the GPL might have consequences on the surroundings.
> I'd say that's a good thing for the kernel, as it increases the chances
> the texts built upon ours remain close to what we expect on this topic.
>
> That's why I currently think using CC-BY is a good idea.

It's a matter of preferences; I like -SA better as a closer match to the
kernel's GPL licensing. But it's your text, so it's your choice.

jon

2020-11-22 05:37:18

[permalink] [raw]

Subject: Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

Am 20.11.20 um 22:58 schrieb Jonathan Corbet:
> On Fri, 20 Nov 2020 11:46:07 +0100
> Thorsten Leemhuis <[email protected]> wrote:
>> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
>>> On Sun, 15 Nov 2020 11:13:52 +0100
>>> Thorsten Leemhuis <[email protected]> wrote:
>>
>>> - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
>>> (or some suitable name). I do wonder if it should also move to the
>>> process manual as part of this; not only admins will report bugs.
>> After a night's sleep and Randy's comment I for now settled on
>> Documentation/admin-guide/reporting-issues.rst
> Keeping it in the admin guide is OK. Not sure about the name, though; if
> you're really dead set against bugs, maybe reporting-problems.rst?

Well, I'm not dead set against bugs, but it somehow seems wrong to me:
people have problems/issues they deal with, which in the end might turn
out to not be a bug/error in the code at all. That afaics why tracker
software for such reports is often called "issue tracker" instead of
"bug tracker" (and nearly nobody calls them problem trackers afaics)..
That's why I went with "issues" in the name and the text.

But in the end I'm not a native English speaker, so I guess it's better
if I follow advice from those. Randy, what would you choose?

> I'd be a bit more straightforward:
>
> This document is obsolete, and will be replaced by
> Documentation/admin-guide/$NAME in the near future.
>
> Not sure that more is really needed?

Totally fine for me (I guess I tried to be less bold and was overly
careful).

@Jonathan, one more question: when I submit this again, should I CC more
people (Linus, Greg, ?) to give them a chance to speak up before this
lands in your tree?

Ciao, Thorsten

2020-11-22 05:46:17