Skip to contentSkip to conversation

Update REPORTING-BUGS

RFC In review Sarah Sharp 6 participants 19 messages Apr 15, 2013 – May 1, 2013

lore
Share & tools
lore
#3 lore raw

RFC 3/7 Docs: Add "Gather info" section to REPORTING-BUGS.

In reply to Sarah Sharp

Add a sub-heading, and emphasize reproducibility.

Suggest taking a picture of the oops message. (Did no one have cameras in 2006?)

---
 REPORTING-BUGS |   26 ++++++++++++++------------
 1 files changed, 14 insertions(+), 12 deletions(-)
REPORTING-BUGS +14 -12
index 6ed518b..f86e500 100644
@@ -44,22 +44,24 @@ http://www.tux.org/lkml/).
 
 [Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]
 
-What follows is a suggested procedure for reporting Linux bugs. You aren't
-obliged to use the bug reporting format, it is provided as a guide to the
-kind of information that can be useful to developers - no more.
+Gather information
+------------------
 
-If the failure includes an "OOPS:" type message in your log or on screen
-please read "Documentation/oops-tracing.txt" before posting your bug
-report. This explains what you should do with the "Oops" information to
-make it useful to the recipient.
+The most important information in a bug report is how to reproduce the
+bug.  This includes system information, and (most importantly)
+step-by-step instructions for how a user can trigger the bug.
 
-If it occurs repeatably try and describe how to recreate it. That is worth
-even more than the oops itself.
+If the failure includes an "OOPS:", take a picture of the screen, capture
+a netconsole trace, or type the message from your screen into the bug
+report.  Please read "Documentation/oops-tracing.txt" before posting your
+bug report. This explains what you should do with the "Oops" information
+to make it useful to the recipient.
 
-This is a suggested format for a bug report sent to the Linux kernel mailing
-list. Having a standardized bug report form makes it easier for you not to
+This is a suggested format for a bug report sent via email or bugzilla.
+Having a standardized bug report form makes it easier for you not to
 overlook things, and easier for the developers to find the pieces of
-information they're really interested in. Don't feel you have to follow it.
+information they're really interested in.  If some information is not
+relevant to your bug, feel free to exclude it.
 
 First run the ver_linux script included as scripts/ver_linux, which
 reports the version of some important subsystems.  Run this script with
Signature · 1 line
1.7.9
#2 lore raw

RFC 2/7 Docs: Step-by-step directions for reporting bugs.

In reply to Sarah Sharp

REPORTING-BUGS is pretty disorganized. Bug reporters are likely to be in a frustrated, stressed frame of mind, so introduce methodical step-by-step directions for how to report bugs. Use titles so people can skim it if necessary.

Slight changes in procedures:

1. Encourage people to report bugs to maintainers and sub-system mailing lists, not LKML at first. I've seen way too many people get lost in the noise because they didn't Cc the maintainer or proper mailing list.

2. Link to bugzilla.kernel.org, and let people know that some maintainers prefer bugs filed there vs. the mailing lists. (Perhaps we need an entry in MAINTAINERS for which is preferred?)

3. If someone doesn't know where to report a bug, encourage them to both file a bugzilla entry and email LKML. Their report is less likely to get lost if there's a bugzilla entry.

Preserve text about reporting security bugs, and get_maintainer.pl.

More will be added/modified in upcoming patches.

---
 REPORTING-BUGS |   65 +++++++++++++++++++++++++++++++++++++++----------------
 1 files changed, 46 insertions(+), 19 deletions(-)
REPORTING-BUGS +46 -19
index ad709e4..6ed518b 100644
@@ -1,3 +1,47 @@
+Identify the problematic subsystem
+----------------------------------
+
+Identifying which part of the Linux kernel might be causing your issue
+increases your chances of getting your bug fixed. Simply posting to the
+generic linux-kernel mailing list (LKML) may cause your bug report to be
+lost in the noise of a mailing list that gets 1000+ emails a day.
+
+Instead, try to figure out which kernel subsystem is causing the issue,
+and email that subsystem's maintainer and mailing list.  If the subsystem
+maintainer doesn't answer, then expand your scope to mailing lists like
+LKML.
+
+
+Identify who to notify
+----------------------
+
+Once you know the subsystem that is causing the issue, you should send a
+bug report.  Some maintainers prefer bugs to be reported via bugzilla
+(https://bugzilla.kernel.org), while others prefer that bugs be reported
+via the subsystem mailing list.
+
+To find out where to send an emailed bug report, find your subsystem or
+device driver in the MAINTAINERS file.  Search in the file for relevant
+entries, and send your bug report to the person(s) listed in the "M:"
+lines, making sure to Cc the mailing list(s) in the "L:" lines.  When the
+maintainer replies to you, make sure to 'Reply-all' in order to keep the
+public mailing list(s) in the email thread.
+
+If you know which driver is causing issues, you can pass one of the driver
+files to the get_maintainer.pl script:
+     perl scripts/get_maintainer.pl -f <filename>
+
+If it is a security bug, please copy the Security Contact listed in the
+MAINTAINERS file.  They can help coordinate bugfix and disclosure.  See
+Documentation/SecurityBugs for more information.
+
+If you can't figure out which subsystem caused the issue, you should file
+a bug in kernel.org bugzilla and send email to
[email protected], referencing the bugzilla URL.  (For more
+information on the linux-kernel mailing list see
+http://www.tux.org/lkml/).
+
+
 [Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]
 
 What follows is a suggested procedure for reporting Linux bugs. You aren't
@@ -9,25 +53,8 @@ please read "Documentation/oops-tracing.txt" before posting your bug
 report. This explains what you should do with the "Oops" information to
 make it useful to the recipient.
 
-Send the output to the maintainer of the kernel area that seems to be
-involved with the problem, and cc the relevant mailing list. Don't worry
-too much about getting the wrong person. If you are unsure send it to the
-person responsible for the code relevant to what you were doing.  If it
-occurs repeatably try and describe how to recreate it. That is worth even
-more than the oops itself.  The list of maintainers and mailing lists is
-in the MAINTAINERS file in this directory.  If you know the file name that
-causes the problem you can use the following command in this directory to
-find some of the maintainers of that file:
-
-     perl scripts/get_maintainer.pl -f <filename>
-
-If it is a security bug, please copy the Security Contact listed in the
-MAINTAINERS file.  They can help coordinate bugfix and disclosure.  See
-Documentation/SecurityBugs for more information.
-
-If you are totally stumped as to whom to send the report, send it to
[email protected]. (For more information on the linux-kernel
-mailing list see http://www.tux.org/lkml/).
+If it occurs repeatably try and describe how to recreate it. That is worth
+even more than the oops itself.
 
 This is a suggested format for a bug report sent to the Linux kernel mailing
 list. Having a standardized bug report form makes it easier for you not to
Signature · 1 line
1.7.9
#4 lore raw

RFC 4/7 Docs: Add info on supported kernels to REPORTING-BUGS.

In reply to Sarah Sharp

One of the most common frustrations maintainers have with bug reporters is the email that starts with "I have a two year old kernel from an embedded vendor with some random drivers and fixes thrown in, and it's crashing".

Be specific about what kernel versions the upstream maintainers will fix bugs in, and direct bug reporters to their Linux distribution or embedded vendor if the bug is in an unsupported kernel.

Suggest that bug reporters should reproduce their bugs on the latest -rc kernel.

---
 REPORTING-BUGS |   22 ++++++++++++++++++++++
 1 files changed, 22 insertions(+), 0 deletions(-)
REPORTING-BUGS +22 -0
index f86e500..c1f6e43 100644
@@ -1,3 +1,25 @@
+Background
+==========
+
+The upstream Linux kernel maintainers only fix bugs for specific kernel
+versions.  Those versions include the current "release candidate" (or -rc)
+kernel, any "stable" kernel versions, and any "long term" kernels.
+
+Please see https://www.kernel.org/ for a list of supported kernels.  Any
+kernel marked with [EOL] is "end of life" and will not have any fixes
+backported to it.
+
+If you've found a bug on a kernel version isn't listed on kernel.org,
+contact your Linux distribution or embedded vendor for support.
+Alternatively, you can attempt to run one of the supported stable or -rc
+kernels, and see if you can reproduce the bug on that.  It's preferable
+to reproduce the bug on the latest -rc kernel.
+
+
+How to report Linux kernel bugs
+===============================
+
+
 Identify the problematic subsystem
 ----------------------------------
 
Signature · 1 line
1.7.9
#6 lore raw

RFC 5/7 Docs: Expectations for bug reporters and maintainers

In reply to Sarah Sharp

Outline how often it's polite to ping kernel maintainers about bugs, and suggest that kernel maintainers should respond to bugs in 1 to 5 business days.

Emphasize that regressions, userspace breakage, and kernel crashes are exceptions to that rule. Suggest escalation to LKML and Linus if these bugs are ignored during the merge window.

Cc Linus Torvalds <[email protected]>
---
 REPORTING-BUGS |   42 +++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 41 insertions(+), 1 deletions(-)
REPORTING-BUGS +41 -1
index c1f6e43..327b33b 100644
@@ -117,4 +117,44 @@ summary from [1.]>" for easy identification by the developers.
 [X.] Other notes, patches, fixes, workarounds:
 
 
-Thank you
+Follow up
+=========
+
+Expectations for bug reporters
+------------------------------
+
+Linux kernel maintainers expect bug reporters to be able to follow up on
+bug reports.  That may include running new tests, applying patches,
+recompiling your kernel, and/or re-triggering your bug.  The most
+frustrating thing for maintainers is for someone to report a bug, and then
+never follow up on a request to try out a fix.
+
+That said, it's still useful for a kernel maintainer to know a bug exists
+on a supported kernel, even if you can't follow up with retests.  Follow
+up reports, such as replying to the email thread with "I tried the latest
+kernel and I can't reproduce my bug anymore" are also helpful, because
+maintainers have to assume silence means things are still broken.
+
+Expectations for kernel maintainers
+-----------------------------------
+
+Linux kernel maintainers are busy, overworked human beings.  Some times
+they may not be able to address your bug in a day, a week, or two weeks.
+If they don't answer your email, they may be on vacation, or at a Linux
+conference.  Check the conference schedule at LWN.net for more info:
+	https://lwn.net/Calendar/
+
+In general, kernel maintainers take 1 to 5 business days to respond to
+bugs.  The majority of kernel maintainers are employed to work on the
+kernel, and they may not work on the weekends.  Maintainers are scattered
+around the world, and they may not work in your time zone.  Unless you
+have a high priority bug, please wait at least a week after the first bug
+report before sending the maintainer a reminder email.
+
+The exceptions to this rule are regressions, kernel crashes, security holes,
+or userspace breakage caused by new kernel behavior.  Those bugs should be
+addressed by the maintainers ASAP.  If you suspect a maintainer is not
+responding to these types of bugs in a timely manner (especially during a
+merge window), escalate the bug to LKML and Linus Torvalds.
+
+Thank you!
Signature · 1 line
1.7.9
#15 lore raw

RFC 7/7 Docs: Move ref to Frohwalt Egerer to end of REPORTING-BUGS

In reply to Sarah Sharp

The document is largely not the same as the original that was crafted from Frohwalt Egerer's document, but leave it in as a historical thank you footnote.

---
 REPORTING-BUGS |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)
REPORTING-BUGS +2 -1
index d397e918..0cb8cdf 100644
@@ -77,7 +77,6 @@ threads or separate bugzilla entries.  If you report several unrelated
 bugs at once, it's difficult for maintainers to tease apart the relevant
 data.
 
-[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]
 
 Gather information
 ------------------
@@ -171,3 +170,5 @@ responding to these types of bugs in a timely manner (especially during a
 merge window), escalate the bug to LKML and Linus Torvalds.
 
 Thank you!
+
+[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]
Signature · 1 line
1.7.9
#0 lore raw

cover Update REPORTING-BUGS

This patchset updates REPORTING-BUGS, and changes some suggested bug reporting procedures. Please review patches 2, 4, and 5 for procedure changes.

Linus, please review patch 5. I know you want to ensure regressions get addressed quickly during the merge window, so I've suggested bug reporters escalate reports to LKML and you if they feel maintainers aren't being responsive. Kernel devs know to do this, but other bug reporters may not.

After these patches, REPORTING-BUGS looks like this:

Background
==========

The upstream Linux kernel maintainers only fix bugs for specific kernel versions. Those versions include the current "release candidate" (or -rc) kernel, any "stable" kernel versions, and any "long term" kernels.

Please see https://www.kernel.org/ for a list of supported kernels. Any kernel marked with [EOL] is "end of life" and will not have any fixes backported to it.

If you've found a bug on a kernel version isn't listed on kernel.org, contact your Linux distribution or embedded vendor for support. Alternatively, you can attempt to run one of the supported stable or -rc kernels, and see if you can reproduce the bug on that. It's preferable to reproduce the bug on the latest -rc kernel.

How to report Linux kernel bugs
===============================

Identify the problematic subsystem
----------------------------------

Identifying which part of the Linux kernel might be causing your issue increases your chances of getting your bug fixed. Simply posting to the generic linux-kernel mailing list (LKML) may cause your bug report to be lost in the noise of a mailing list that gets 1000+ emails a day.

Instead, try to figure out which kernel subsystem is causing the issue, and email that subsystem's maintainer and mailing list. If the subsystem maintainer doesn't answer, then expand your scope to mailing lists like LKML.

Identify who to notify
----------------------

Once you know the subsystem that is causing the issue, you should send a bug report. Some maintainers prefer bugs to be reported via bugzilla
(https://bugzilla.kernel.org), while others prefer that bugs be reported via the subsystem mailing list.

To find out where to send an emailed bug report, find your subsystem or device driver in the MAINTAINERS file. Search in the file for relevant entries, and send your bug report to the person(s) listed in the "M:" lines, making sure to Cc the mailing list(s) in the "L:" lines. When the maintainer replies to you, make sure to 'Reply-all' in order to keep the public mailing list(s) in the email thread.

If you know which driver is causing issues, you can pass one of the driver files to the get_maintainer.pl script:
perl scripts/get_maintainer.pl -f <filename>

If it is a security bug, please copy the Security Contact listed in the MAINTAINERS file. They can help coordinate bugfix and disclosure. See Documentation/SecurityBugs for more information.

If you can't figure out which subsystem caused the issue, you should file a bug in kernel.org bugzilla and send email to [email protected], referencing the bugzilla URL. (For more information on the linux-kernel mailing list see
http://www.tux.org/lkml/).

Tips for reporting bugs
-----------------------

If you haven't reported a bug before, please read:

http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
http://www.catb.org/esr/faqs/smart-questions.html

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

The most important information in a bug report is how to reproduce the bug. This includes system information, and (most importantly) step-by-step instructions for how a user can trigger the bug.

If the failure includes an "OOPS:", take a picture of the screen, capture a netconsole trace, or type the message from your screen into the bug report. Please read "Documentation/oops-tracing.txt" before posting your bug report. This explains what you should do with the "Oops" information to make it useful to the recipient.

This is a suggested format for a bug report sent via email or bugzilla. Having a standardized bug report form makes it easier for you not to overlook things, and easier for the developers to find the pieces of information they're really interested in. If some information is not relevant to your bug, feel free to exclude it.

First run the ver_linux script included as scripts/ver_linux, which reports the version of some important subsystems. Run this script with the command "sh scripts/ver_linux".

Use that information to fill in all fields of the bug report form, and post it to the mailing list with a subject of "PROBLEM: <one line summary from [1.]>" for easy identification by the developers.

[1.] One line summary of the problem:
[2.] Full description of the problem/report:
[3.] Keywords (i.e., modules, networking, kernel):
[4.] Kernel information
[4.1.] Kernel version (from /proc/version):
[4.2.] Kernel .config file:
[5.] Most recent kernel version which did not have the bug:
[6.] Output of Oops.. message (if applicable) with symbolic information
resolved (see Documentation/oops-tracing.txt)
[7.] A small shell script or example program which triggers the
problem (if possible)
[8.] Environment
[8.1.] Software (add the output of the ver_linux script here) [8.2.] Processor information (from /proc/cpuinfo):
[8.3.] Module information (from /proc/modules):
[8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) [8.5.] PCI information ('lspci -vvv' as root)
[8.6.] SCSI information (from /proc/scsi/scsi)
[8.7.] Other information that might be relevant to the problem
(please look in /proc and include all information that you think to be relevant):
[X.] Other notes, patches, fixes, workarounds:

Follow up
=========

Expectations for bug reporters
------------------------------

Linux kernel maintainers expect bug reporters to be able to follow up on bug reports. That may include running new tests, applying patches, recompiling your kernel, and/or re-triggering your bug. The most frustrating thing for maintainers is for someone to report a bug, and then never follow up on a request to try out a fix.

That said, it's still useful for a kernel maintainer to know a bug exists on a supported kernel, even if you can't follow up with retests. Follow up reports, such as replying to the email thread with "I tried the latest kernel and I can't reproduce my bug anymore" are also helpful, because maintainers have to assume silence means things are still broken.

Expectations for kernel maintainers
-----------------------------------

Linux kernel maintainers are busy, overworked human beings. Some times they may not be able to address your bug in a day, a week, or two weeks. If they don't answer your email, they may be on vacation, or at a Linux conference. Check the conference schedule at LWN.net for more info:
https://lwn.net/Calendar/

In general, kernel maintainers take 1 to 5 business days to respond to bugs. The majority of kernel maintainers are employed to work on the kernel, and they may not work on the weekends. Maintainers are scattered around the world, and they may not work in your time zone. Unless you have a high priority bug, please wait at least a week after the first bug report before sending the maintainer a reminder email.

The exceptions to this rule are regressions, kernel crashes, security holes, or userspace breakage caused by new kernel behavior. Those bugs should be addressed by the maintainers ASAP. If you suspect a maintainer is not responding to these types of bugs in a timely manner (especially during a merge window), escalate the bug to LKML and Linus Torvalds.

Thank you!

[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]

The following changes since commit bb33db7a076f4719dc68c235e187dd4bfb16b621:

Merge branches 'timers-urgent-for-linus', 'irq-urgent-for-linus' and 'core-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip (2013-04-15 07:03:01 -0700)

are available in the git repository at:

git://git.kernel.org/pub/scm/linux/kernel/git/sarah/xhci.git documentation

for you to fetch changes up to 8d874c1030e1ae4c174d8f947841ee3ee196f898:

Docs: Move ref to Frohwalt Egerer to end of REPORTING-BUGS (2013-04-15 10:10:23 -0700)

----------------------------------------------------------------
Sarah Sharp (7):
Trivial: docs: Remove six-space indentation in REPORTING-BUGS.
Docs: Step-by-step directions for reporting bugs.
Docs: Add "Gather info" section to REPORTING-BUGS.
Docs: Add info on supported kernels to REPORTING-BUGS.
Docs: Expectations for bug reporters and maintainers
Docs: Add a tips section to REPORTING-BUGS.
Docs: Move ref to Frohwalt Egerer to end of REPORTING-BUGS

 REPORTING-BUGS |  162 ++++++++++++++++++++++++++++++++++++++++++++++----------
 1 files changed, 134 insertions(+), 28 deletions(-)
#1 lore raw

RFC 1/7 Trivial: docs: Remove six-space indentation in REPORTING-BUGS.

Other paragraph format docs in Documentation don't use paragraph indentations, so conform REPORTING-BUGS to that.

Re-wrap the paragraphs, keeping the doc to a 74-character line length, since that's what the original seemed to use.

---
 REPORTING-BUGS |   43 ++++++++++++++++++++++---------------------
 1 files changed, 22 insertions(+), 21 deletions(-)
REPORTING-BUGS +22 -21
index 55a6074..ad709e4 100644
@@ -1,30 +1,31 @@
 [Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]
 
-     What follows is a suggested procedure for reporting Linux bugs. You
-aren't obliged to use the bug reporting format, it is provided as a guide
-to the kind of information that can be useful to developers - no more.
+What follows is a suggested procedure for reporting Linux bugs. You aren't
+obliged to use the bug reporting format, it is provided as a guide to the
+kind of information that can be useful to developers - no more.
 
-     If the failure includes an "OOPS:" type message in your log or on
-screen please read "Documentation/oops-tracing.txt" before posting your
-bug report. This explains what you should do with the "Oops" information
-to make it useful to the recipient.
+If the failure includes an "OOPS:" type message in your log or on screen
+please read "Documentation/oops-tracing.txt" before posting your bug
+report. This explains what you should do with the "Oops" information to
+make it useful to the recipient.
+
+Send the output to the maintainer of the kernel area that seems to be
+involved with the problem, and cc the relevant mailing list. Don't worry
+too much about getting the wrong person. If you are unsure send it to the
+person responsible for the code relevant to what you were doing.  If it
+occurs repeatably try and describe how to recreate it. That is worth even
+more than the oops itself.  The list of maintainers and mailing lists is
+in the MAINTAINERS file in this directory.  If you know the file name that
+causes the problem you can use the following command in this directory to
+find some of the maintainers of that file:
 
-      Send the output to the maintainer of the kernel area that seems to
-be involved with the problem, and cc the relevant mailing list. Don't
-worry too much about getting the wrong person. If you are unsure send it
-to the person responsible for the code relevant to what you were doing.
-If it occurs repeatably try and describe how to recreate it. That is
-worth even more than the oops itself.  The list of maintainers and
-mailing lists is in the MAINTAINERS file in this directory.  If you
-know the file name that causes the problem you can use the following
-command in this directory to find some of the maintainers of that file:
      perl scripts/get_maintainer.pl -f <filename>
 
-      If it is a security bug, please copy the Security Contact listed
-in the MAINTAINERS file.  They can help coordinate bugfix and disclosure.
-See Documentation/SecurityBugs for more information.
+If it is a security bug, please copy the Security Contact listed in the
+MAINTAINERS file.  They can help coordinate bugfix and disclosure.  See
+Documentation/SecurityBugs for more information.
 
-      If you are totally stumped as to whom to send the report, send it to
+If you are totally stumped as to whom to send the report, send it to
 [email protected]. (For more information on the linux-kernel
 mailing list see http://www.tux.org/lkml/).
 
@@ -33,7 +34,7 @@ list. Having a standardized bug report form makes it easier for you not to
 overlook things, and easier for the developers to find the pieces of
 information they're really interested in. Don't feel you have to follow it.
 
-      First run the ver_linux script included as scripts/ver_linux, which
+First run the ver_linux script included as scripts/ver_linux, which
 reports the version of some important subsystems.  Run this script with
 the command "sh scripts/ver_linux".
 
Signature · 1 line
1.7.9
#14 lore raw

RFC 6/7 Docs: Add a tips section to REPORTING-BUGS.

In reply to Sarah Sharp

Lots of grumpy maintainers would love to have annoying newbies and disorganized bug reporters read Eric S. Raymond's "How To Ask Questions The Smart Way". Simon Tatham's "How to Report Bugs Effectively" is also relevant.

It's likely no one will bother to read these, but it does give maintainers something to point to.

---
 REPORTING-BUGS |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)
REPORTING-BUGS +13 -0
index 327b33b..d397e918 100644
@@ -64,6 +64,19 @@ information on the linux-kernel mailing list see
 http://www.tux.org/lkml/).
 
 
+Tips for reporting bugs
+-----------------------
+
+If you haven't reported a bug before, please read:
+
+http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
+http://www.catb.org/esr/faqs/smart-questions.html
+
+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.
+
 [Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]
 
 Gather information
Signature · 1 line
1.7.9
#16 lore raw
In reply to Sarah Sharp
Quoted 6 lines · Sarah Sharp

Linus, please review patch 5. I know you want to ensure regressions get addressed quickly during the merge window, so I've suggested bug reporters escalate reports to LKML and you if they feel maintainers aren't being responsive. Kernel devs know to do this, but other bug reporters may not.

Looks fine to me. You can change the "Cc:" to an "Acked-by:"

LInus

#18 lore raw

Thanks Ted!

Quoted 7 lines · Theodore Ts'o

Sarah,

Thanks so much for improving the REPORTING-BUGS file. With your changes it looks way better!

- Ted

#5 lore raw

Re: [RFC 4/7] Docs: Add info on supported kernels to REPORTING-BUGS.

In reply to Sarah Sharp
Quoted 8 lines · Sarah Sharp

One of the most common frustrations maintainers have with bug reporters is the email that starts with "I have a two year old kernel from an embedded vendor with some random drivers and fixes thrown in, and it's crashing".

Be specific about what kernel versions the upstream maintainers will fix bugs in, and direct bug reporters to their Linux distribution or embedded vendor if the bug is in an unsupported kernel.

Back in 2006 I wrote a section of the BusyBox FAQ about this:

http://git.busybox.net/busybox/tree/docs/busybox.net/FAQ.html?id=95718b3091690f1293e3069da75d0d4be2665d0e#n359

(Alas, the current version of that page had a large project specific chunk dumped into the middle of it, but the text I linked to out of the repo is reasonably generic to just about any project. Feel free to lift anything that's useful. :)

Rob

#7 lore raw

Re: [RFC 5/7] Docs: Expectations for bug reporters and maintainers

In reply to Sarah Sharp
Quoted 3 lines · Sarah Sharp

Outline how often it's polite to ping kernel maintainers about bugs, and suggest that kernel maintainers should respond to bugs in 1 to 5 business days.

Is there anything in here about the four-level nature of modern maintainership?

Patches go from the developer, to the maintainer, to one of Linus's lieutenants, to Linus himself. If you submit a patch to a maintainer they owe you a response. The lieutenant (subsystem maintainer) owes that maintainer a response, and Linus (the project's architect) owes the lieutenant a response.

Linus does not owe you, personally, a response. Neither do the subsystem maintainers if you approach them directly with something that should have gone through one of the hundreds of domain-specific maintainers out of the Maintainers file. So the point of going to the right people in sequence and getting their review and signed-off-by lines is to ensure you don't sit there listening to crickets chirping while your patch is ignored. (If you approach Linus directly you may randomly _get_ a response, but there's no guarantee, and usually you won't because he's really busy.)

Rob

#8 lore raw

Re: [RFC 5/7] Docs: Expectations for bug reporters and maintainers

Quoted 6 lines · Rob Landley
Quoted 4 lines · Sarah Sharp

Outline how often it's polite to ping kernel maintainers about bugs, and
suggest that kernel maintainers should respond to bugs in 1 to 5 business days.

Quoted 8 lines

Is there anything in here about the four-level nature of modern maintainership?

Patches go from the developer, to the maintainer, to one of Linus's lieutenants, to Linus himself. If you submit a patch to a maintainer they owe you a response. The lieutenant (subsystem maintainer) owes that maintainer a response, and Linus (the project's architect) owes the lieutenant a response.

Do we want to go into this much detail in a document meant for frustrated bug reporters? Or perhaps we should create a separate document about the kernel maintainer hierarchy and reference it here?

Also, please note that I'm writing this from the perspective of a driver maintainer. I'm not sure if we've met face to face. :)

Quoted 9 lines

Linus does not owe you, personally, a response. Neither do the subsystem maintainers if you approach them directly with something that should have gone through one of the hundreds of domain-specific maintainers out of the Maintainers file. So the point of going to the right people in sequence and getting their review and signed-off-by lines is to ensure you don't sit there listening to crickets chirping while your patch is ignored. (If you approach Linus directly you may randomly _get_ a response, but there's no guarantee, and usually you won't because he's really busy.)

This file is about bug reporting, not submitting patches. I rewrote this file for the audience of people who would like to report a kernel bug, but don't necessarily want to track it down and submit a patch themselves. Since this file isn't about submitting patches, let's focus the discussion on bug reporters.

I agree that bug reporting should be done from the bottom up. That's why I tried to thoroughly explain how to find the right contact from MAINTAINERS or get_maintainer.pl.

However, if a driver maintainer is not doing their job, is not responding to regressions, it makes sense to escalate that up the chain. Security holes in unmaintained code cause problems for anyone that uses the Linux kernel, since distro kernels tend to turn nearly every config option on. If code is not being maintained, it may be better to remove it, or at least mark it as depending on CONFIG_BROKEN.

If a driver maintainer isn't responding to a bug or security hole in a timely manner, it makes sense to escalate that to the subsystem maintainer who merges their patches. Perhaps the driver maintainer is on vacation, and the subsystem maintainer can tell the bug reporter they'll have to wait. Or maybe the driver maintainer has disappeared completely from kernel development, and it's time someone else stepped into their place. Either way, the subsystem maintainer's job is to make sure their subsystem is maintained by the driver maintainers under them.

If the subsystem maintainer doesn't respond, and it's a critical issue, the last-ditch effort to get it fixed may need to be contacting Linus. If there's serious code issues with a particular subsystem (like we've seen in the past with the graphics subsystem or the ARM arch code), then it makes sense for Linus to know about it.

TLDR version: Yes, it would be nice if bug reporters could go up the hierarchy, but they don't have an easy way to know which subsystem maintainers to contact. Perhaps a new line in MAINTAINERS for the subsystem maintainer would be helpful?

Sarah Sharp

#9 lore raw

Re: [RFC 5/7] Docs: Expectations for bug reporters and maintainers

Quoted 16 lines · Sarah Sharp
Quoted 6 lines · Rob Landley
Quoted 4 lines · Sarah Sharp

Outline how often it's polite to ping kernel maintainers about bugs, and
suggest that kernel maintainers should respond to bugs in 1 to 5 business days.

Quoted 8 lines

Is there anything in here about the four-level nature of modern maintainership?

Patches go from the developer, to the maintainer, to one of Linus's lieutenants, to Linus himself. If you submit a patch to a maintainer they owe you a response. The lieutenant (subsystem maintainer) owes that maintainer a response, and Linus (the project's architect) owes the lieutenant a response.

Quoted 3 lines

Do we want to go into this much detail in a document meant for frustrated bug reporters? Or perhaps we should create a separate document about the kernel maintainer hierarchy and reference it here?

My point was that you have to contact the right person to semi-reliably get a response, but you're right. That's more about getting patches in than getting problems reproduced and diagnosed.

Quoted 2 lines

Also, please note that I'm writing this from the perspective of a driver maintainer. I'm not sure if we've met face to face. :)

Pretty sure we haven't. (You helped me debug a weird usb3 issue once via email.)

Quoted 11 lines
Quoted 9 lines

Linus does not owe you, personally, a response. Neither do the subsystem maintainers if you approach them directly with something that should have gone through one of the hundreds of domain-specific maintainers out of the Maintainers file. So the point of going to the right people in sequence and getting their review and signed-off-by lines is to ensure you don't sit there listening to crickets chirping while your patch is ignored. (If you approach Linus directly you may randomly _get_ a response, but there's no guarantee, and usually you won't because he's really busy.)

This file is about bug reporting, not submitting patches. I rewrote

...

Quoted 4 lines

TLDR version: Yes, it would be nice if bug reporters could go up the hierarchy, but they don't have an easy way to know which subsystem maintainers to contact. Perhaps a new line in MAINTAINERS for the subsystem maintainer would be helpful?

Eh, this has gone undocumented for a full decade and nobody but me's cared. It seemed related at the time (general interacting with the kernel developers), but I guess not.

Rob

#10 lore raw

Re: [RFC 5/7] Docs: Expectations for bug reporters and maintainers

Quoted 17 lines · Rob Landley
Quoted 16 lines · Sarah Sharp
Quoted 14 lines · Rob Landley
Quoted 4 lines · Sarah Sharp

Outline how often it's polite to ping kernel maintainers about bugs, and
suggest that kernel maintainers should respond to bugs in 1 to 5 business days.

Is there anything in here about the four-level nature of modern maintainership?

Patches go from the developer, to the maintainer, to one of Linus's lieutenants, to Linus himself. If you submit a patch to a maintainer they owe you a response. The lieutenant (subsystem maintainer) owes that maintainer a response, and Linus (the project's architect) owes the lieutenant a response.

Quoted 7 lines
Quoted 3 lines

Do we want to go into this much detail in a document meant for frustrated bug reporters? Or perhaps we should create a separate document about the kernel maintainer hierarchy and reference it here?

My point was that you have to contact the right person to semi-reliably get a response, but you're right. That's more about getting patches in than getting problems reproduced and diagnosed.

No worries! I think it's really useful for patch submitters to get their work to the right maintainers as well. That description just doesn't belong here. :)

Quoted 9 lines
Quoted 1 line

This file is about bug reporting, not submitting patches.

...

Quoted 4 lines

TLDR version: Yes, it would be nice if bug reporters could go up the hierarchy, but they don't have an easy way to know which subsystem maintainers to contact. Perhaps a new line in MAINTAINERS for the subsystem maintainer would be helpful?

It seemed related at the time (general interacting with the kernel developers), but I guess not.

Ok. Do you think the new line in MAINTAINERS would be useful as a separate patch? Possibly if it came from the subsystem maintainers themselves?

Quoted 2 lines

Eh, this has gone undocumented for a full decade and nobody but me's cared.

I think it's less "nobody but me's cared" and more "no one with knowledge of the community is willing to write basic documentation that is needed". People care, just not the ones with enough expertise to write docs.

I do care about good documentation, so I suspect you'll be getting more patches from me in the future. :)

Any other feedback on this patchset? If not, are you going to send it to Linus for 3.10 or should I?

Sarah Sharp

#12 lore raw

Re: [RFC 5/7] Docs: Expectations for bug reporters and maintainers

In reply to Sarah Sharp
Quoted 4 lines · Sarah Sharp

TLDR version: Yes, it would be nice if bug reporters could go up the hierarchy, but they don't have an easy way to know which subsystem maintainers to contact. Perhaps a new line in MAINTAINERS for the subsystem maintainer would be helpful?

We have that already for a number of subsystems, look at the entry for "USB SUBSYSTEM" for one such example, and there are 49 others in there as well :)

Thanks for rewriting this document, it looks much better now.

greg k-h

#11 lore raw

Re: [RFC 5/7] Docs: Expectations for bug reporters and maintainers

In reply to Sarah Sharp
Quoted 2 lines · Sarah Sharp

Any other feedback on this patchset? If not, are you going to send it to Linus for 3.10 or should I?

Go for it, I still need to pitch a new tent on kernel.org now that I've got my login back. (Touch overscheduled the past couple months...) Meanwhile I've just been forwarding patches to the trivial tree when they fall through the cracks.

Quoted 1 line

Sarah Sharp

Rob

#13 lore raw

Re: [RFC 5/7] Docs: Expectations for bug reporters and maintainers

In reply to Sarah Sharp
Quoted 11 lines · Sarah Sharp
Quoted 5 lines · Rob Landley

Patches go from the developer, to the maintainer, to one of Linus's lieutenants, to Linus himself. If you submit a patch to a maintainer they owe you a response. The lieutenant (subsystem maintainer) owes that maintainer a response, and Linus (the project's architect) owes the lieutenant a response.

Do we want to go into this much detail in a document meant for frustrated bug reporters? Or perhaps we should create a separate document about the kernel maintainer hierarchy and reference it here?

The rule of thumb I tend to give people here is to make sure that the people who tend to sign off changes to the driver are on the mail. Not everyone is comfortable with git but if they are that's fairly easy to do.