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(-)
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.
Signed-off-by: Sarah Sharp <[email protected]>
---
REPORTING-BUGS | 65 +++++++++++++++++++++++++++++++++++++++----------------
1 files changed, 46 insertions(+), 19 deletions(-)
diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index ad709e4..6ed518b 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -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
--
1.7.9
Add a sub-heading, and emphasize reproducibility.
Suggest taking a picture of the oops message. (Did no one have cameras
in 2006?)
Signed-off-by: Sarah Sharp <[email protected]>
---
REPORTING-BUGS | 26 ++++++++++++++------------
1 files changed, 14 insertions(+), 12 deletions(-)
diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index 6ed518b..f86e500 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -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
--
1.7.9
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.
Signed-off-by: Sarah Sharp <[email protected]>
Cc: Linus Torvalds <[email protected]>
---
REPORTING-BUGS | 42 +++++++++++++++++++++++++++++++++++++++++-
1 files changed, 41 insertions(+), 1 deletions(-)
diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index c1f6e43..327b33b 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -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!
--
1.7.9
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.
Signed-off-by: Sarah Sharp <[email protected]>
---
REPORTING-BUGS | 22 ++++++++++++++++++++++
1 files changed, 22 insertions(+), 0 deletions(-)
diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index f86e500..c1f6e43 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -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
----------------------------------
--
1.7.9
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.
Signed-off-by: Sarah Sharp <[email protected]>
---
REPORTING-BUGS | 43 ++++++++++++++++++++++---------------------
1 files changed, 22 insertions(+), 21 deletions(-)
diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index 55a6074..ad709e4 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -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".
--
1.7.9
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.
Signed-off-by: Sarah Sharp <[email protected]>
---
REPORTING-BUGS | 3 ++-
1 files changed, 2 insertions(+), 1 deletions(-)
diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index d397e918..0cb8cdf 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -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]
--
1.7.9
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.
Signed-off-by: Sarah Sharp <[email protected]>
---
REPORTING-BUGS | 13 +++++++++++++
1 files changed, 13 insertions(+), 0 deletions(-)
diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index 327b33b..d397e918 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -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
--
1.7.9
On Mon, Apr 15, 2013 at 10:33 AM, Sarah Sharp
<[email protected]> wrote:
>
> 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
Sarah,
Thanks so much for improving the REPORTING-BUGS file. With your
changes it looks way better!
- Ted
Thanks Ted!
On Mon, Apr 15, 2013 at 09:47:42PM -0400, Theodore Ts'o wrote:
> Sarah,
>
> Thanks so much for improving the REPORTING-BUGS file. With your
> changes it looks way better!
>
>
> - Ted
On 04/15/2013 12:33:33 PM, Sarah Sharp wrote:
> 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-
On 04/15/2013 12:33:34 PM, Sarah Sharp wrote:
> 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-
On Tue, Apr 16, 2013 at 09:15:06PM -0500, Rob Landley wrote:
> On 04/15/2013 12:33:34 PM, Sarah Sharp wrote:
> >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.
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. :)
> 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
On 04/17/2013 01:23:28 PM, Sarah Sharp wrote:
> On Tue, Apr 16, 2013 at 09:15:06PM -0500, Rob Landley wrote:
> > On 04/15/2013 12:33:34 PM, Sarah Sharp wrote:
> > >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.
>
> 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.
> 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.)
> > 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
...
> 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-
On Wed, Apr 17, 2013 at 06:49:40PM -0500, Rob Landley wrote:
> On 04/17/2013 01:23:28 PM, Sarah Sharp wrote:
> >On Tue, Apr 16, 2013 at 09:15:06PM -0500, Rob Landley wrote:
> >> On 04/15/2013 12:33:34 PM, Sarah Sharp wrote:
> >> >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.
> >
> >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. :)
> >This file is about bug reporting, not submitting patches.
> ...
> >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?
> 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
On Wed, Apr 17, 2013 at 11:23:28AM -0700, Sarah Sharp wrote:
> 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
On 04/18/2013 06:52:45 PM, Sarah Sharp wrote:
> 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.
> Sarah Sharp
Rob
On Wed, Apr 17, 2013 at 11:23:28AM -0700, Sarah Sharp wrote:
> On Tue, Apr 16, 2013 at 09:15:06PM -0500, Rob Landley wrote:
> > 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.