From nobody Sun Feb 8 21:48:07 2026 Received: from wp530.webpack.hosteurope.de (wp530.webpack.hosteurope.de [80.237.130.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 9A9702D7DCD; Sun, 26 Oct 2025 12:42:30 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.237.130.52 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482553; cv=none; b=HYIIJq+FYDuTOotvWvRJMdBai4GQZlYokj2CIKeFfHBl2mnK0wgxmxHzC5louNsD73DrWRvwde5V4c4/ciphOfeJIPNPbPtBMirPNgtJHhoOftSAkItYNZmm9cxV96+8p+jD+LFlRFopNnBVONn3n4VCXmYhEwJcsxpUWexXkEQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482553; c=relaxed/simple; bh=VFMjt34iiE7rL173jXtwP9Qu1mZQyBO5BjezitHnlfk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Wl1Fy6l8P3n0ch5QfOwHEtjSKivaIVf87NPSBjt7cxe/qeUick6zecZLgVQNLnbF+pS+7AEyNkNvKboTkUDeGKEsDkrii+pUvbTx4fuZlzbLU9pywVdsrkyWKKqQkfLryPuIvARhTHzJfFG0m1gd5QTbW0wg5BGQqv/0/fUokgo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=leemhuis.info; spf=pass smtp.mailfrom=leemhuis.info; dkim=pass (2048-bit key) header.d=leemhuis.info header.i=@leemhuis.info header.b=fbF2fMxh; arc=none smtp.client-ip=80.237.130.52 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=leemhuis.info Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=leemhuis.info Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=leemhuis.info header.i=@leemhuis.info header.b="fbF2fMxh" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=leemhuis.info; s=he214686; h=Content-Transfer-Encoding:MIME-Version: References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From:From:Sender: Reply-To:Subject:Date:Message-ID:To:Cc:MIME-Version:Content-Type: Content-Transfer-Encoding:Content-ID:Content-Description:In-Reply-To: References; bh=LBImDqI3AgmfnWBCE/oEL79UonVWSQFWC9Yg5W3f/io=; t=1761482550; x=1761914550; b=fbF2fMxhG53BJymHDjgVGq2uCJkJBVgvoGam5xVUEGCOUljQP20WM+s/I0PeQ rPgmNe0hXR2gOjrkCi0O0OIhbHwfnAFSjbFcP/w3cNGgclOGEhRzbGKcMCBrffj9jauVqQ3Ap7QQ7 cj8bqDaBMTcmzOTUWEwIVuYV+o35F+Sj1UQK97WIiMJlWsUnNDQf52y9TC/0uSGJsOkUi+fJxwOSv A2yd0ZqZk+cDYCrEhAZ1jItP+dRvlJzXOSQgZXndqQHEXHq2AxNEDdu8w6h5pQ1JnhMlyOjQ/dPYb 2xCzpYg371nTiRQSqZUCOmfT7lbnUyF8Dep6zn6+DY4R13yRzw==; Received: from [2a02:8108:8984:1d00:a8ad:ebd4:6fc6:160] (helo=luggage.fritz.box); authenticated by wp530.webpack.hosteurope.de running ExIM with esmtpsa (TLS1.3:ECDHE_X25519__RSA_PSS_RSAE_SHA256__AES_256_GCM:256) id 1vD04q-001mYF-3A; Sun, 26 Oct 2025 13:42:29 +0100 From: Thorsten Leemhuis To: Jonathan Corbet Cc: workflows@vger.kernel.org, linux-doc@vger.kernel.org, regressions@lists.linux.dev, linux-kernel@vger.kernel.org Subject: [PATCH v1 18/30] docs: reporting-issues: improve text on looking up place to report Date: Sun, 26 Oct 2025 13:42:09 +0100 Message-ID: <9d3ad70d6b0eb75b4d32e5ba04ad3bd3d3d66621.1761481839.git.linux@leemhuis.info> X-Mailer: git-send-email 2.51.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1761482550;db804c08; X-HE-SMSGID: 1vD04q-001mYF-3A Content-Type: text/plain; charset="utf-8" Fine-tune the instructions about checking the MAINTAINERS file. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 169 +++++++++--------- 1 file changed, 86 insertions(+), 83 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index e9d304040e3b54..56e004ba038403 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -149,10 +149,13 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 - * Locate the driver or kernel subsystem that seems to be causing the issu= e. - Find out how and where its developers expect reports. Note: most of the - time this won't be bugzilla.kernel.org, as issues typically need to be = sent - by mail to a maintainer and a public mailing list. +.. _maintainers_repisbs: + +* *You must* consult ':ref:`MAINTAINERS `' to determine where + developers of the affected driver or subsystem want bugs to be submitted= to; + use your best guess if in doubt which is appropriate. + + [:ref:`details `] =20 * Create a fresh backup and put system repair and restore tools at hand. =20 @@ -705,119 +708,121 @@ answer these emails on a best-effort basis. [:ref:`back to step-by-step guide `] =20 =20 -Check where you need to report your issue ------------------------------------------ +.. _maintainers_repiref: =20 - *Locate the driver or kernel subsystem that seems to be causing the is= sue. - Find out how and where its developers expect reports. Note: most of the - time this won't be bugzilla.kernel.org, as issues typically need to be= sent - by mail to a maintainer and a public mailing list.* +Check how to report your issue +------------------------------ =20 -It's crucial to send your report to the right people, as the Linux kernel = is a + *You must consult MAINTAINERS to determine where developers of the affec= ted + driver or subsystem want bugs to be submitted to; use your best guess, i= f* [:ref:`... `] + +It is crucial to submit your report to the right place, as the Linux kerne= l is a big project and most of its developers are only familiar with a small subs= et of -it. Quite a few programmers for example only care for just one driver, for -example one for a WiFi chip; its developer likely will only have small or = no -knowledge about the internals of remote or unrelated "subsystems", like th= e TCP -stack, the PCIe/PCI subsystem, memory management or file systems. +it. Quite a few programmers, for example, only care for just one driver, l= ike +one for a particular WiFi chip; its developer likely will only have small = or no +knowledge about the internals of near, remote, or unrelated subsystems, li= ke +the TCP stack, the PCIe/PCI subsystem, memory management, or file systems. =20 -Problem is: the Linux kernel lacks a central bug tracker where you can sim= ply +Problem is: The Linux kernel lacks a central bug tracker where you can sim= ply file your issue and make it reach the developers that need to know about i= t. -That's why you have to find the right place and way to report issues yours= elf. +That is why you have to find the right place and way to report issues your= self. You can do that with the help of a script (see below), but it mainly targe= ts -kernel developers and experts. For everybody else the MAINTAINERS file is = the -better place. +kernel developers and experts. For everybody else, using the MAINTAINERS f= ile is +the better approach. =20 How to read the MAINTAINERS file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + To illustrate how to use the :ref:`MAINTAINERS ` file, let's = assume -the WiFi in your Laptop suddenly misbehaves after updating the kernel. In = that -case it's likely an issue in the WiFi driver. Obviously it could also be s= ome -code it builds upon, but unless you suspect something like that stick to t= he -driver. If it's really something else, the driver's developers will get the -right people involved. +the WiFi in your Laptop misbehaves. In that +case it is likely an issue in the WiFi driver. Obviously it could also be = some +underlying code from other subsystems, but unless something hints at that, +stick to the driver; if it is really something else, the driver's develope= rs +will involve the +right people. =20 Sadly, there is no way to check which code is driving a particular hardware component that is both universal and easy. =20 -In case of a problem with the WiFi driver you for example might want to lo= ok at -the output of ``lspci -k``, as it lists devices on the PCI/PCIe bus and the +In case of a problem with the WiFi driver, you, for example, might want to= look +at the output of ``lspci -k``, as it lists devices on the PCI/PCIe bus and= the kernel module driving it:: =20 - [user@something ~]$ lspci -k - [...] - 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wirel= ess Network Adapter (rev 32) - Subsystem: Bigfoot Networks, Inc. Device 1535 - Kernel driver in use: ath10k_pci - Kernel modules: ath10k_pci - [...] + [user@something ~]$ lspci -k + [...] + 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless = Network Adapter (rev 32) + Subsystem: Bigfoot Networks, Inc. Device 1535 + Kernel driver in use: ath10k_pci + Kernel modules: ath10k_pci + [...] =20 But this approach won't work if your WiFi chip is connected over USB or so= me -other internal bus. In those cases you might want to check your WiFi manag= er or -the output of ``ip link``. Look for the name of the problematic network +other internal bus. In those cases you might want to check your network ma= nager +or the output of ``ip link``. Look for the name of the problematic network interface, which might be something like 'wlp58s0'. This name can be used = like this to find the module driving it:: =20 - [user@something ~]$ realpath --relative-to=3D/sys/module/ /sys/clas= s/net/wlp58s0/device/driver/module - ath10k_pci + [user@something ~]$ realpath --relative-to=3D/sys/module/ /sys/class/ne= t/wlp58s0/device/driver/module + ath10k_pci =20 In case tricks like these don't bring you any further, try to search the internet on how to narrow down the driver or subsystem in question. And if= you -are unsure which it is: just try your best guess, somebody will help you i= f you -guessed poorly. +are unsure which it is: Just try your best guess, somebody will usually he= lp out +if you guessed poorly. =20 Once you know the driver or subsystem, you want to search for it in the MAINTAINERS file. In the case of 'ath10k_pci' you won't find anything, as = the name is too specific. Sometimes you will need to search on the net for hel= p; -but before doing so, try a somewhat shorted or modified name when searchin= g the -MAINTAINERS file, as then you might find something like this:: - - QUALCOMM ATHEROS ATH10K WIRELESS DRIVER - Mail: A. Some Human - Mailing list: ath10k@lists.infradead.org - Status: Supported - Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/at= h10k - SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kv= alo/ath.git - Files: drivers/net/wireless/ath/ath10k/ - -Note: the line description will be abbreviations, if you read the plain -MAINTAINERS file found in the root of the Linux source tree. 'Mail:' for -example will be 'M:', 'Mailing list:' will be 'L', and 'Status:' will be '= S:'. -A section near the top of the file explains these and other abbreviations. - -First look at the line 'Status'. Ideally it should be 'Supported' or +but before doing so, try a somewhat shortened or modified name when search= ing +the MAINTAINERS file, as then you might find something like this:: + + QUALCOMM ATHEROS ATH10K WIRELESS DRIVER + Mail: A. Some Human + Mailing list: ath10k@lists.infradead.org + Status: Supported + Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k + SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/= ath.git + Files: drivers/net/wireless/ath/ath10k/ + +Note: Line descriptions like 'Status' will be abbreviations like 'S:' if y= ou +read the plain MAINTAINERS file found in the root of the Linux source tree. + +First look at the line 'Status' ('S:'). Ideally it should be 'Supported' or 'Maintained'. If it states 'Obsolete' then you are using some outdated app= roach that was replaced by a newer solution you need to switch to. Sometimes the= code only has someone who provides 'Odd Fixes' when feeling motivated. And with 'Orphan' you are totally out of luck, as nobody takes care of the code any= more. -That only leaves these options: arrange yourself to live with the issue, f= ix it +That only leaves these options: Arrange yourself to live with the issue, f= ix it yourself, or find a programmer somewhere willing to fix it. =20 -After checking the status, look for a line starting with 'bugs:': it will = tell -you where to find a subsystem specific bug tracker to file your issue. The +After checking the status, look for a line starting with 'bugs:' ('B:'): It +will tell you where to find a subsystem-specific bug tracker to file your +issue. The example above does not have such a line. That is the case for most section= s, as -Linux kernel development is completely driven by mail. Very few subsystems= use +Linux kernel development is completely driven by email: Very few subsystem= s use a bug tracker, and only some of those rely on bugzilla.kernel.org. =20 -In this and many other cases you thus have to look for lines starting with -'Mail:' instead. Those mention the name and the email addresses for the +In this and many other cases, you thus have to look for lines starting with +'Mail:' ('M:') instead. Those mention the name and the email addresses for= the maintainers of the particular code. Also look for a line starting with 'Ma= iling -list:', which tells you the public mailing list where the code is develope= d. -Your report later needs to go by mail to those addresses. Additionally, fo= r all -issue reports sent by email, make sure to add the Linux Kernel Mailing List -(LKML) to CC. Don't omit either of the mail= ing -lists when sending your issue report by mail later! Maintainers are busy p= eople -and might leave some work for other developers on the subsystem specific l= ist; -and LKML is important to have one place where all issue reports can be fou= nd. +List:' ('L:'), which tells you the public mailing list where the code is +developed. Your report later needs to go by email to those addresses. +Additionally, for all issue reports sent by email, make sure to add the Li= nux +Kernel Mailing List (LKML) to CC. Don't omit +either of the mailing lists when sending your issue report by email later! +Maintainers are busy people and might leave some work for other developers= on +the subsystem-specific list -- and LKML is important to have one place whe= re all +issue reports can be found. =20 =20 Finding the maintainers with the help of a script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -For people that have the Linux sources at hand there is a second option to= find -the proper place to report: the script 'scripts/get_maintainer.pl' which t= ries +For people that have the Linux sources at hand, there is a second option t= o find +the proper place to report: The script 'scripts/get_maintainer.pl' which t= ries to find all people to contact. It queries the MAINTAINERS file and needs t= o be called with a path to the source code in question. For drivers compiled as -module if often can be found with a command like this:: +module, it often can be found with a command like this:: =20 $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!= ; s!filename:!!; s!\.ko\(\|\.xz\)!!' drivers/net/wireless/ath/ath10k/ath10k_pci.ko @@ -832,20 +837,18 @@ Pass parts of this to the script:: netdev@vger.kernel.org (open list:NETWORKING DRIVERS) linux-kernel@vger.kernel.org (open list) =20 -Don't sent your report to all of them. Send it to the maintainers, which t= he -script calls "supporter:"; additionally CC the most specific mailing list = for -the code as well as the Linux Kernel Mailing List (LKML). In this case you= thus -would need to send the report to 'Some Human ' with -'ath10k@lists.infradead.org' and 'linux-kernel@vger.kernel.org' in CC. +Usually you want to send your report to all of them. =20 -Note: in case you cloned the Linux sources with git you might want to call +Note: In case you cloned the Linux sources with Git, you might want to call ``get_maintainer.pl`` a second time with ``--git``. The script then will l= ook at the commit history to find which people recently worked on the code in -question, as they might be able to help. But use these results with care, = as it -can easily send you in a wrong direction. That for example happens quickly= in -areas rarely changed (like old or unmaintained drivers): sometimes such co= de is -modified during tree-wide cleanups by developers that do not care about the -particular driver at all. +question, as they might be able to help. But use these results with care, = as +they can easily send you in the wrong direction. That, for example, happens +quickly in areas rarely changed (like old or unmaintained drivers): Someti= mes +such code is modified during tree-wide cleanups by developers that do not = care +about the particular driver at all. + +[:ref:`back to step-by-step guide `] =20 =20 Prepare for emergencies --=20 2.51.0