From nobody Sun Feb 8 13:08:52 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 44ECB2D4814; 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=1761482554; cv=none; b=tqKKfmuvzeshZ5oCTI8nGbFyQekgOV+53HPCCVnWTiT7OFHJl8CUSBpZnEBBfzp7cQaVffDN86lfcZki/HrmLG9zhNon4I1g7j9wVhP/B64saGe0GwzcU0eyaW1PrfRSHeJ2M8r1O4Qj3n+1vaQ2aHTDgN/o05lVa0KIQQYoRMA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482554; c=relaxed/simple; bh=xAI5YfEuTiDep83Xgs+jcdtCYrUUTepDFLMFVQqhTlM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=cPRrJQpJmQXF4+02npv2b/JbawDd8brNFh2TnW7hVXzdhOCYsFnLemOS+yHLgYO4REGRlsaDmNS5e8EoxpGqImnGR5dBE+CYymLQ9IjYoexsP6LyMgkcotbfiXzbT+/GgSbRksZ6It/hfileQdPrrv06Apie28L0aAbdJPXoCH0= 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=wJIDYZY+; 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="wJIDYZY+" 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=634MWhFAXgdF+Ly2EAEMkXBMHvbyAhbHlX3frr8jsXI=; t=1761482550; x=1761914550; b=wJIDYZY+KjnmVBLrvThs0s9Qr5UUJfgaVUuDyqbv2BjZ/gD4i/bvCKKOWb894 09HTdZTrJzhow+UOLyY0+nUyI2d61skoNxHCjQyIhqCG2cUfdVcumEzkWRVliKANDEZKYYf7OwuoH ee4XO24aN+EVtcOeXxLH1AIanGZ404DUtBFpU/fefUaszztjedtfvlShAA7KiZtwuYYzUEk2ZaQt6 oXhZKFpZwwgfL9tZGLaK/iCIByehS7KDV5L79f6DJoArfF8CPsrM7rkUh3G6Vmqxruiz1RyPs/oGh UCKIQXcFtqtQoRbsuxx1JMv9wk47dQjNBNGseoefNb9mZL3F4Q==; 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 1vD04k-001mX6-1V; Sun, 26 Oct 2025 13:42:22 +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 01/30] docs: reporting-issues: mention text is best viewed rendered Date: Sun, 26 Oct 2025 13:41:52 +0100 Message-ID: <4f7e2de2a2336c52e55cc49dcda627a4e86b8793.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: 1vD04k-001mX6-1V Content-Type: text/plain; charset="utf-8" Add a comment before the step-by-step guide explaining that the document is best viewed in the rendered form, as there the internal links will work that later patches will add. While at it change the double quotes in the license hint at the end of the document into single quotes, which is the preferred style. Signed-off-by: Thorsten Leemhuis --- Documentation/admin-guide/reporting-issues.rst | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index a68e6d90927471..3bc47afaf85ea0 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -48,6 +48,16 @@ Once the report is out, answer any questions that come u= p and help where you can. That includes keeping the ball rolling by occasionally retesting with= newer releases and sending a status update afterwards. =20 +.. + Note: If you see this note, you are reading the text's source file. You + might want to switch to a rendered version: It makes it a lot easier to + read and navigate this document -- especially when you want to look som= ething + up in the reference section, then jump back to where you left off. +.. + Find the latest rendered version of this text here: + https://docs.kernel.org/admin-guide/reporting-issues.html + + Step-by-step guide how to report issues to the kernel maintainers =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -1748,13 +1758,13 @@ art will lay some groundwork to improve the situati= on over time. you spot a typo or small mistake, feel free to let him know directly and he'll fix it. You are free to do the same in a mostly informal way if y= ou want to contribute changes to the text, but for copyright reasons pleas= e CC - linux-doc@vger.kernel.org and "sign-off" your contribution as - Documentation/process/submitting-patches.rst outlines in the section "S= ign - your work - the Developer's Certificate of Origin". + linux-doc@vger.kernel.org and 'sign-off' your contribution as + Documentation/process/submitting-patches.rst outlines in the section 'S= ign + your work - the Developer's Certificate of Origin'. .. This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top of the file. If you want to distribute this text under CC-BY-4.0 only, - please use "The Linux kernel developers" for author attribution and link + please use 'The Linux kernel developers' for author attribution and link this as source: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plai= n/Documentation/admin-guide/reporting-issues.rst .. --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 44D682D0635; 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=1761482552; cv=none; b=DHGhvAoLarVwnTBiCdnq8DVPGGCzctUYECbDPcvmsQ1t2Q1ZJKBcJN+xvtXcRJlpP2sb6RGJJUeeAOoKU/N9WSGl8cUwfVFNjB1kx8kaHWQimyPiPWZvQtAGdzV5Uh517LO5bnxDiEzTqHEc24JFrId5GZuLGMNhCpYnvqHMQcQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482552; c=relaxed/simple; bh=yyf519215u2MDdtHhsuvS1aHgIQQ/WJ2C5bOX/X38zg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Qm++xG5mog+SIGyw+Kb2yGbxStQMCrTNbssYaplriCIA9m8jeqt5wx+o4UEbkWoggptthwuAmjIFQyHBQ7UXBbswviVow9PDLCa3OzPgz6n5X7DoucB7qFWeC24sdhd0Exj0p3ovgSslOa3Oq99F4Yxul1IdMxv2Fxu1OG+aVIg= 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=HsVf0ULQ; 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="HsVf0ULQ" 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=+90988As5O3leaoO212A9P2dJ7//kwlH5PvTRnoE+AY=; t=1761482550; x=1761914550; b=HsVf0ULQv3aIaBYOLHIa4TAun6Z2ffZSFGsRWQaiuF1a9yJZczZoEof8EEJDO 9hNuqeB1KsNdOE1msHA8UDpbK0wNzs+Te40uI2+QYDul6hVeP0F/XMsgMyAxqyalySSoIyXSMIjMG R692WIDamDf9RYkiHLPBLtCm7gSPCCxf+FtRHKAJA5puX1nSH1dkVCyI0TVRJFhtCadWtWnKvm5lr ONlUEA7Gj7BeqrJYr96+S2YZh3VXIwdZ2AkxvrMVo+P6ouukfzdv6fYcUYcM0Qf3UWZ4y1iTCRFN2 JVREu9lOdmP4vpOSIn2CQ9CD8AtqI6zy+vpEg+njhLetujVYXQ==; 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 1vD04k-001mX6-31; Sun, 26 Oct 2025 13:42:23 +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 02/30] docs: reporting-issues: tweak the reference section intro Date: Sun, 26 Oct 2025 13:41:53 +0100 Message-ID: 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: 1vD04k-001mX6-31 Content-Type: text/plain; charset="utf-8" Small improvements to the intro of the reference section. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 67 +++++++++---------- 1 file changed, 31 insertions(+), 36 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 3bc47afaf85ea0..90b50c27c0d2b6 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -244,42 +244,37 @@ The reference section below explains each of these st= eps in more detail. Reference section: Reporting issues to the kernel maintainers =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -The detailed guides above outline all the major steps in brief fashion, wh= ich -should be enough for most people. But sometimes there are situations where= even -experienced users might wonder how to actually do one of those steps. That= 's -what this section is for, as it will provide a lot more details on each of= the -above steps. Consider this as reference documentation: it's possible to re= ad it -from top to bottom. But it's mainly meant to skim over and a place to look= up -details how to actually perform those steps. - -A few words of general advice before digging into the details: - - * The Linux kernel developers are well aware this process is complicated = and - demands more than other FLOSS projects. We'd love to make it simpler. B= ut - that would require work in various places as well as some infrastructur= e, - which would need constant maintenance; nobody has stepped up to do that - work, so that's just how things are for now. - - * A warranty or support contract with some vendor doesn't entitle you to - request fixes from developers in the upstream Linux kernel community: s= uch - contracts are completely outside the scope of the Linux kernel, its - development community, and this document. That's why you can't demand - anything such a contract guarantees in this context, not even if the - developer handling the issue works for the vendor in question. If you w= ant - to claim your rights, use the vendor's support channel instead. When do= ing - so, you might want to mention you'd like to see the issue fixed in the - upstream Linux kernel; motivate them by saying it's the only way to ens= ure - the fix in the end will get incorporated in all Linux distributions. - - * If you never reported an issue to a FLOSS project before you should con= sider - reading `How to Report Bugs Effectively - `_, `How To Ask - Questions The Smart Way - `_, and `How to ask = good - questions `_. - -With that off the table, find below the details on how to properly report -issues to the Linux kernel developers. +The step-by-step guide above outlines all the major steps in brief fashion, +which usually covers everything required. But even experienced users will +sometimes wonder how to actually realize some of those steps or why they a= re +needed; there are also corner cases the guide ignores for readability. Tha= t is +what the entries in this reference section are for, which provide addition= al +information for each of the steps in the detailed guide. + +A few words of general advice: + +* The Linux kernel developers are well aware that reporting bugs to them is + more complicated and demanding than in other FLOSS projects. Quite a few + would love to make it simpler. But that would require convincing a lot of + developers to change their habits; it, furthermore, would require improv= ements + on several technical fronts and people that constantly take care of vari= ous + things. Nobody has stepped up to do or fund that work. + +* A warranty or support contract with some vendor doesn't entitle you to + request fixes from the upstream Linux developers: Such contracts are + completely outside the scope of the upstream Linux kernel, its developme= nt + community, and this document -- even if those handling the issue work fo= r the + vendor who issued the contract. If you want to claim your rights, use the + vendor's support channel. + +* If you never reported an issue to a FLOSS project before, consider skimm= ing + guides like `How to ask good questions + `_, `How To Ask Questions The Smar= t Way + `_, and `How to Report + Bugs Effectively `_,. + +With that off the table, find below details for the steps from the detailed +guide on reporting issues to the Linux kernel developers. =20 =20 Make sure you're using the upstream Linux kernel --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 44F4B2D7392; 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=1761482552; cv=none; b=meSKktRm3j6N09AG6f9dUMnvZv89SGggNHX5RpSqxSluCLoMaVlsr9pJMcBC2ailM9dA3PfCKHHN6D0A/zqtraku9G9lbJ9cQP0jrB25ODM2BFzJxB8d7lttepLc4mF7my/PjXOD4dn5/MS8dRfN7xd8FNlbj3FjiPrt3NBHWvs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482552; c=relaxed/simple; bh=44O02KX0DN7+jAJrnarViS3KTXfGoY/g/3iIWB//p/I=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=UNtOBUACLLcqqB0UXMAoV3soMlfW33vNt0tyOQveaZil0AavU19jQAAvR0PNSOh/ExfZNf5+ozJAnAgrqOzQzCQIEvSUoBxTq3jfYzPobbQ/lmUaSeNzSoSaWLFS/5maqpLt8hH1c//CLIBO+jBhkZVs4cnYmLmEC9XC9qjnZUg= 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=JQdIhOp5; 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="JQdIhOp5" 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=PKnQQRxCkYFmTCA5kI5Xv69vsVtqU4WtvO3WAuNhaEo=; t=1761482550; x=1761914550; b=JQdIhOp5f3KcUw1d7pfJCAmlnh9050+scBFqU/h3M1qK874xdN8/Mg+GBjppg HKu7gze51LwqHSAALVYAhXbKi65NykQg68vLmDCXaDsTmwUJC+CHqq7tEX3suGDtuVPXQE9QqwH5T 3DMRkjz7PkzrM0I7Vn51kHpkj+okFYRR+NM12/JRo6fHkeh5iCYq1ZrbGpxKEcu6yNtBeG7w/OnL1 5K7ofd1bJgTZUDoFiYb4dVz22yKrAKi2os2tTbld0Cc3+yiy21Z2czhEYJxviUziMtozVWYF4AjdI rWpiI0iCnmyL9aOEYHSZEFVvUeblNLO7VOxpGtbaSnUF5FuV/g==; 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 1vD04l-001mX6-1E; Sun, 26 Oct 2025 13:42:23 +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 03/30] docs: reporting-issues: add conclusion to the step-by-step guide Date: Sun, 26 Oct 2025 13:41:54 +0100 Message-ID: <9a8d7b58f482cf0669bc5028dd0e01301f7f526e.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: 1vD04l-001mX6-1E Content-Type: text/plain; charset="utf-8" Idea and text comes from Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst Signed-off-by: Thorsten Leemhuis --- Documentation/admin-guide/reporting-issues.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 90b50c27c0d2b6..9676ba85e1b73c 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -241,6 +241,20 @@ kernels regularly rebased on those. If that is the cas= e, follow these steps: The reference section below explains each of these steps in more detail. =20 =20 +Conclusion of the step-by-step guide +------------------------------------ + +Did you run into trouble following the step-by-step guide not cleared up b= y the +reference section below? Did you spot errors? Or do you have ideas on how = to +improve the guide? + +If any of that applies, please take a moment and let the primary author of= this +text, Thorsten Leemhuis , know by email while ideally= CCing +the public Linux docs mailing list . Such feedb= ack is +vital to improve this text further, which is in everybody's interest, as i= t will +enable more people to master the task described here. + + Reference section: Reporting issues to the kernel maintainers =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 756022C11EC; Sun, 26 Oct 2025 12:42:31 +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=hF+cg/MqzpSc29RrumNLRHLTzTjyCSyGVxOmsH9hutv81DAOn5F+NHk8Fa+3EwhmPLgp9pDbF2eoiEsXgC56IdOZ+YP3keh5N9ZfqZYuM2GmSxz/OeCcJ6kwg0wqLQQAUv483OKrCJO3E0j5A7ZGWCkOnxBbq1p2YgDyYOa+u8k= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482553; c=relaxed/simple; bh=j11Gc/5QYiUy6F+P2RyEr/2EB+XN5KyxRXrWVYzN3t0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=C18BgROYjQGpprHsUzv3Gpf+hTPK/jLeVnfHlYYt1I5iAG2OSjvGAvwvLyWr2HSjZbMwCGZ52XAgLRqUWvpwxP04Tls4g1XI+vjfHd6olGSm52LIdUL6SYfu03WyUU9HffNzSuOIhoHKzMoz350MfYi+OGebTm9cJw4H00XRWE8= 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=dxWmeTjd; 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="dxWmeTjd" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=leemhuis.info; s=he214686; h=Content-Transfer-Encoding:Content-Type: 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=+oSFmLCLJ2XeD/SLV19HCOuUmPh+XxTv83L0oJR/kUU=; t=1761482551; x=1761914551; b=dxWmeTjda+jjl2pCaR3qB/GCv4fs1xC0xbQUtz4y06QXBX89+QRzZwm7GZ0PS 2KPt7XO6Ajap2JU3csRU2vBJ97LHxmkWdDVCIkGzIiHhgK2T9Cl5ujFp8gw2iLuDAAlO1pXQBI0KS qI7NpBm1JQ3qLc0w3RXCBhZVwi9YGPXjagCSjCAp4xCUs0Vev+1EJ7qYt4zh7cipJuNEt0d8uXFvK vaeYmPkVVlaoZlUu0oSav752YlgB9gYugtRaPowyjiDaXAVpGzkCnTZ0FnrWZFsxoXGEXdLQIWsh3 oxN3i0O3w/3sqNGghprEqHf6rSJ25Ndn8Y/oCA2C3I04rTH3Nw==; 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 1vD04l-001mX6-2O; Sun, 26 Oct 2025 13:42:23 +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 04/30] docs: reporting-issues: add proper appendix Date: Sun, 26 Oct 2025 13:41:55 +0100 Message-ID: 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-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1761482551;009d26c6; X-HE-SMSGID: 1vD04l-001mX6-2O Turn the "Why some bugs remain unfixed and some report are ignored" section into a proper appendix while improving it slightly. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 102 +++++++++--------- 1 file changed, 54 insertions(+), 48 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 9676ba85e1b73c..745e698cb6be8b 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -1693,60 +1693,66 @@ for the subsystem where the issue seems to have its= roots; CC the mailing list for the subsystem as well as the stable mailing list (stable@vger.kernel.o= rg). =20 =20 -Why some issues won't get any reaction or remain unfixed after being repor= ted -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D +Appendix: additional background information +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -When reporting a problem to the Linux developers, be aware only 'issues of= high -priority' (regressions, security issues, severe problems) are definitely g= oing -to get resolved. The maintainers or if all else fails Linus Torvalds himse= lf -will make sure of that. They and the other kernel developers will fix a lo= t of -other issues as well. But be aware that sometimes they can't or won't help= ; and -sometimes there isn't even anyone to send a report to. +.. _unfixedbugs_repiapdx: =20 -This is best explained with kernel developers that contribute to the Linux -kernel in their spare time. Quite a few of the drivers in the kernel were -written by such programmers, often because they simply wanted to make their -hardware usable on their favorite operating system. +Why some bugs remain unfixed and some report are ignored +-------------------------------------------------------- + +When reporting a problem to the Linux developers, be aware that they are o= nly +obliged to fix regressions, security issues, and severe problems. Develope= rs, +maintainers, or, if all else fails, Linus Torvalds himself will make sure = of +that. They will fix a lot of other issues as well, but sometimes they can'= t or +won't help -- and sometimes there isn't even anyone to send a report to. + +This situation is best explained using kernel developers that contribute t= o the +Linux kernel in their spare time. Quite a few of the drivers in the kernel= were +written by such programmers; often they simply wanted to make the +hardware they owned usable on their favorite operating system. =20 These programmers most of the time will happily fix problems other people -report. But nobody can force them to do, as they are contributing voluntar= ily. - -Then there are situations where such developers really want to fix an issu= e, -but can't: sometimes they lack hardware programming documentation to do so. -This often happens when the publicly available docs are superficial or the -driver was written with the help of reverse engineering. - -Sooner or later spare time developers will also stop caring for the driver. -Maybe their test hardware broke, got replaced by something more fancy, or = is so -old that it's something you don't find much outside of computer museums -anymore. Sometimes developer stops caring for their code and Linux at all,= as -something different in their life became way more important. In some cases -nobody is willing to take over the job as maintainer =E2=80=93 and nobody = can be forced -to, as contributing to the Linux kernel is done on a voluntary basis. Aban= doned -drivers nevertheless remain in the kernel: they are still useful for peopl= e and -removing would be a regression. +report. But nobody can force them to do so, as they are contributing +voluntarily. + +There are also situations where such developers would like to fix issues, +but can't: They might lack programming documentation to do so or hardware = to +test. The former can happen when the publicly available docs are superfici= al or +when a driver was written with the help of reverse engineering. + +Sooner or later, spare-time developers usually stop caring for the driver. +Maybe their test hardware broke, was replaced by something more fancy, or +became so old that it is something you don't find much outside of computer +museums anymore. Other times developers also stop caring when +something different in life becomes more important to them. Then sometimes +nobody is willing to take over the job as maintainer -- and nobody else ca= n be +forced to, as contributing is voluntary. The code nevertheless often stays +around, as it is useful for people; removing it would also cause a regress= ion, +which is not allowed in Linux. =20 The situation is not that different with developers that are paid for their -work on the Linux kernel. Those contribute most changes these days. But th= eir -employers sooner or later also stop caring for their code or make its -programmer focus on other things. Hardware vendors for example earn their = money -mainly by selling new hardware; quite a few of them hence are not investing -much time and energy in maintaining a Linux kernel driver for something th= ey -stopped selling years ago. Enterprise Linux distributors often care for a -longer time period, but in new versions often leave support for old and ra= re -hardware aside to limit the scope. Often spare time contributors take over= once -a company orphans some code, but as mentioned above: sooner or later they = will -leave the code behind, too. - -Priorities are another reason why some issues are not fixed, as maintainers -quite often are forced to set those, as time to work on Linux is limited. -That's true for spare time or the time employers grant their developers to -spend on maintenance work on the upstream kernel. Sometimes maintainers al= so -get overwhelmed with reports, even if a driver is working nearly perfectly= . To -not get completely stuck, the programmer thus might have no other choice t= han -to prioritize issue reports and reject some of them. - -But don't worry too much about all of this, a lot of drivers have active +work on the upstream Linux kernel. Those contribute the most changes these= days. +But their employers set the priorities. And those sooner or later stop car= ing +for some code or make their +employees focus on other things. Hardware vendors, for example, earn their= money +mainly by selling new hardware -- they thus often are not much interested = in +investing much time and energy in maintaining a Linux kernel driver for a = chip +they stopped selling years ago. Enterprise Linux distributors often care f= or a +longer time period, but in new versions might set support for old and rare +hardware aside to limit the scope, too. Often spare-time contributors take= over +once employed developers orphan some code, but as mentioned earlier: Soone= r or +later they will usually leave the code behind, too. + +Priorities are another reason why some issues are not fixed, as developers +quite often are forced to set those: The spare-time of volunteers or the t= ime +employers allot for upstream Linux kernel work is often limited. Sometimes +developers are also flooded with good and bad reports, even if a driver is +working well. To +not get completely stuck, the programmers might have no other choice than +to prioritize bug reports and ignore some. + +But do not worry too much about all of this, a lot of drivers have active maintainers who are quite interested in fixing as many issues as possible. =20 =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 7567E2C17A8; Sun, 26 Oct 2025 12:42:31 +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=SWmHU1VIH5WwvuamHQoBMJgQIh7HfBYm0uCryepGQz2O7EHqp0ONGTyEvXsnjqVefffGnyXQjt/j8smmLr10NsZVWdZDnKUZCnSzAKz1jB7jBkJhsnu0JlfnKxGTzGoWEC5gV6HjA4JJF4logHPxSlTAm/JuMkXsj2W1e6ga/vc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482553; c=relaxed/simple; bh=vghudGEOY3L1ytcEYABOWe472CPzB9vVvZz/X1Px26A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=AkNH1QkYFM0MLLUKpzPVcZA5VJs21Tne2faliEtjfIy0A1zEt8GtHhhIKv1PhENRIUMg9BbZogaojv57B9t8IeBwUBVeraCTQscQGoeeoMO1r/sPI90vlFWjHPIReSTXZGqJuvQr8so7hIYKEMYdQ4nm22NabdhcP37r2DBc/SE= 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=DcEcOzku; 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="DcEcOzku" 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=A9M9qnXAKMMmJCdLmCAyHsjy98RtFl6ZF9DFi+xuUB8=; t=1761482551; x=1761914551; b=DcEcOzkuAxLLQ9iCDWvClnYTOvNO++ZqYAJygDLgZPxd5NdejNLZQbhQzRDd7 p0ucvKsmxYeLuZdM+yuIMoQtBP6uitMi7TwyOUWmrxf/UsSVTzoCNcW2KYu9dS7mnomM1uO7N3v/m yaUUBtsd2046oKrWA1Ir+rRJGNrK6YrUViKu1xk9eYuIUMWiWnQfU8i5Ik4lR3aN2YUxxWHzjvbuE AaaqDWuB5970iXOJfMcPMxp0jo5ulBzI8yHH0wPcwcpBSKGFXbOvDqdT40UJt4JgqQ5rzdBhCUxjS KABWrOwpze7pg1O3rJXmfd+/CmVgBM0f9XtOfzh52hQv2XB1CQ==; 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 1vD04m-001mXP-12; Sun, 26 Oct 2025 13:42:24 +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 05/30] docs: reporting-issues: outline why reporting is complicated Date: Sun, 26 Oct 2025 13:41:56 +0100 Message-ID: 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;1761482551;009d26c6; X-HE-SMSGID: 1vD04m-001mXP-12 Content-Type: text/plain; charset="utf-8" Replace the closing words with a section that describes why reporting Linux kernel bugs is more complicated than in other FLOSS projects. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 67 ++++++++++++++++--- 1 file changed, 59 insertions(+), 8 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 745e698cb6be8b..2629fde3aa4b8f 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -1756,14 +1756,65 @@ But do not worry too much about all of this, a lot = of drivers have active maintainers who are quite interested in fixing as many issues as possible. =20 =20 -Closing words -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -Compared with other Free/Libre & Open Source Software it's hard to report -issues to the Linux kernel developers: the length and complexity of this -document and the implications between the lines illustrate that. But that'= s how -it is for now. The main author of this text hopes documenting the state of= the -art will lay some groundwork to improve the situation over time. +Why reporting Linux kernel bugs is somewhat complicated +------------------------------------------------------- + +The Linux kernel's development model differs from typical Open Source proj= ects +in a few important aspects. Four of those complicate bug reporting: + +1. Developers are free to solely focus on the latest mainline codebase. + +2. The 'stable team' maintains the stable and longterm kernel series, but = is not + allowed to fix many bugs just there if they happen in mainline, too. + +3. There is no central bug tracker. + +4. Most kernels used in Linux distributions are totally unsuitable for rep= orting + bugs upstream. + +Due to the first aspect, some of the developers ignore or react coldly to +reports about bugs in, say, Linux 6.1 when 6.2-rc1 is already out. + +The combination of the first and the second aspect is why some of the +developers are unwilling to look into reports with stable or longterm kern= els: +the problem might never have happened in the code they work on, for example +because the stable team did something wrong between 6.1.1 and 6.1.2. + +The stable team due to those two aspects is often in a similar but opposite +situation when it comes to bugs reported using a kernel like 6.1.2: If that +issue already happened in 6.1 and still happens in the latest mainline ker= nel, +then it must be fixed there first. That is among the reasons why reporters= in +the end always have to check if mainline is affected, as the stable team o= ften +is the wrong point of contact, unless it is a series specific regression. + +There are various reasons why no central bug tracker exists. They, among o= thers, +were not a thing yet when Linux started, which is why reporting my email w= as +the norm initially -- and still is, as quite a few developers prefer to ha= ndle +all aspects of kernel development via email. Some, on the other hand, saw +benefits in trackers and set up bugzilla.kernel.org, which due to the +aforementioned aspect never became mandatory and has some problematic aspe= cts; +this is why it frequently does not even forward newly filed reports to the +appropriate developers. Yet other developers prefer the comfort of Git for= ges +for development and issue tracking; but subsystems use various forges, so = those +trackers are spread over the web. + +The fourth aspect is explained in the second point of the reference section +already: Old codebases, modified sources, and add-ons lead to bugs that we= re +fixed a long time ago already or never happened upstream in the first plac= e. +These are problems for many other software packaged by Linux distributions= as +well. But there it is usually a smaller problem, as the modifications and +extensions distributors apply to the kernel are often much bigger and more +dangerous; the kernel also changes way more quickly, is a lot more +complex, and naturally more fragile. Due to these aspects, many developers +expect reports to be based on fresh and vanilla kernels. Furthermore, most= of +them receive way more bug reports than they are able to handle, which is +why they prioritize the ones that look more promising. + +Reporting a bug due to these and other unmentioned aspects is harder than = in +other Free/Libre & Open Source Software projects -- the complexity of this +document proves that. But that is the state of affairs for now. The primary +author of this text hopes documenting it will lay some groundwork to impro= ve +the situation over time. =20 =20 .. --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3E60D2DA776; Sun, 26 Oct 2025 12:42:32 +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=1761482555; cv=none; b=bOiPB3X0yArEXxQfKcqo0gys3ePqiOhDv3yTUf/kXpNsCRVRKbSFNrwAPBLd6k++oWtFKMUAgoyUqj7ueratvlNm8Ft6cb/+1alNPzaENw4xRsa4VoI+5Xd9CEnIRg02kptDsLoIA11+zT5R4IK8k3kxtQLEpbxj0f+lhysl9eg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482555; c=relaxed/simple; bh=Jzpn3cEHJuR4e/7Diq2X/A/kIMNuV6RmqTVz+GOnCgQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=pVi5mpLFqHdniYDMTJJxqTrBVKwjfacO1zwI5h+Oj2qm3l4Q3toYyEKnq7BbfxjplZJ7eilreL4BURKFZwp/AZpzDQ5YEVVqH8TNV9B1XX8KiC0w+PTpwZ/M1VZuc/z09kprvl6VbtuGT0h7luPB+GMIC8bl+iULFzy4uRztsvU= 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=vashsqxB; 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="vashsqxB" 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=MCwTNgmIFvfobjvhJBYW7voWM3a+ip/YtfYapTlN3Nk=; t=1761482552; x=1761914552; b=vashsqxBZFUm+HfTEbYOYjsDfL5o7wXov+/rwaX7X0JmOY9+/9nuK0OLVoPPV SSZt/4fz7wdwwFQXeKwppx+er6M8HTXrcsx0yUORhZtoruKc+zpjsMOpDHyKPK7fNtwRJ7PrGFUYK /TF3e+02Ms2d2agTpAg2aHgtcjnV6U1sbAPTA5UVZUSd9YmAwa3dpZMzPn9HP0bnJJlX0VULSyJW/ XB9RlRnp6BHI0cgj+ii4AXlacDFBKk8AEFXv3HLaPLGwB9deaFn10XuQeZtJwTTguPeGsbd9cpZ2U E+iO9FqEtI723Frq5I0m3VHPXpoWEqp/h4pzdodB86WBraAQGg==; 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 1vD04m-001mXP-22; Sun, 26 Oct 2025 13:42:24 +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 06/30] docs: reporting-issues: replace TLDR guide with more of an into Date: Sun, 26 Oct 2025 13:41:57 +0100 Message-ID: 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;1761482552;81a32109; X-HE-SMSGID: 1vD04m-001mXP-22 Content-Type: text/plain; charset="utf-8" Remove the TLDR guide and just describe the essence: a email is all that is needed. Signed-off-by: Thorsten Leemhuis --- --- .../admin-guide/reporting-issues.rst | 90 +++++++------------ 1 file changed, 32 insertions(+), 58 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 2629fde3aa4b8f..7dfb3ca4b3e322 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -4,49 +4,34 @@ Reporting issues ++++++++++++++++ =20 - -The short guide (aka TL;DR) -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D - -Are you facing a regression with vanilla kernels from the same stable or -longterm series? One still supported? Then search the `LKML -`_ and the `Linux stable mailing list -`_ archives for matching reports to join.= If -you don't find any, install `the latest release from that series -`_. If it still shows the issue, report it to the sta= ble -mailing list (stable@vger.kernel.org) and CC the regressions list -(regressions@lists.linux.dev); ideally also CC the maintainer and the mail= ing -list for the subsystem in question. - -In all other cases try your best guess which kernel part might be causing = the -issue. Check the :ref:`MAINTAINERS ` file for how its develop= ers -expect to be told about problems, which most of the time will be by email = with a -mailing list in CC. Check the destination's archives for matching reports; -search the `LKML `_ and the web, too. If you -don't find any to join, install `the latest mainline kernel -`_. If the issue is present there, send a report. - -The issue was fixed there, but you would like to see it resolved in a still -supported stable or longterm series as well? Then install its latest relea= se. -If it shows the problem, search for the change that fixed it in mainline a= nd -check if backporting is in the works or was discarded; if it's neither, ask -those who handled the change for it. - -**General remarks**: When installing and testing a kernel as outlined abov= e, -ensure it's vanilla (IOW: not patched and not using add-on modules). Also = make -sure it's built and running in a healthy environment and not already taint= ed -before the issue occurs. - -If you are facing multiple issues with the Linux kernel at once, report ea= ch -separately. While writing your report, include all information relevant to= the -issue, like the kernel and the distro used. In case of a regression, CC the -regressions mailing list (regressions@lists.linux.dev) to your report. Als= o try -to pinpoint the culprit with a bisection; if you succeed, include its -commit-id and CC everyone in the sign-off-by chain. - -Once the report is out, answer any questions that come up and help where y= ou -can. That includes keeping the ball rolling by occasionally retesting with= newer -releases and sending a status update afterwards. +An email with a problem description sent to the appropriate developers and +mailing lists -- that is all it takes to report a Linux kernel bug. + +This might sound easy, but be aware: Your bug reporting experience is like= ly to +become tedious or fruitless unless you get a few implicit aspects right. + +The Linux kernel used, for example, must ideally be a recent mainline vers= ion; +longterm kernels will rarely do the trick, unless for reporting series-spe= cific +regressions. That alone makes the vast majority of kernels shipped by hard= ware +vendors and Linux distributors unsuitable for upstream reporting. But those +almost always are inadequate anyway, as most are built from modified sourc= es or +use externally developed kernel modules. Both aspects can lead to issues t= hat +never occurred with the upstream Linux kernel, which is why most of its +developers do not really care about bugs reported with such kernels. + +Identifying how to submit a report is also easier said than done. The file +MAINTAINERS answers this and usually points to email addresses. But a small +number of subsystems prefer reports through one of various bug trackers. B= ugs +with most graphics drivers have to go to https://gitlab.freedesktop.org/dr= m/; +https://bugzilla.kernel.org seems like a universal place, but it is rarely= the +right destination, as submissions there often do not even reach the develo= pers. + +The stable team, furthermore, is only the right point of contact for regre= ssions +within a particular stable or longterm kernel series that at the same time= do +not happen with latest mainline -- which you thus have to rule out first. + +To avoid an ineffective, frustrating, or fruitless bug reporting experienc= e, it +thus is in your best interest to follow the step-by-step guide below. =20 .. Note: If you see this note, you are reading the text's source file. You @@ -58,22 +43,11 @@ releases and sending a status update afterwards. https://docs.kernel.org/admin-guide/reporting-issues.html =20 =20 -Step-by-step guide how to report issues to the kernel maintainers -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -The above TL;DR outlines roughly how to report issues to the Linux kernel -developers. It might be all that's needed for people already familiar with -reporting issues to Free/Libre & Open Source Software (FLOSS) projects. For -everyone else there is this section. It is more detailed and uses a -step-by-step approach. It still tries to be brief for readability and leav= es -out a lot of details; those are described below the step-by-step guide in a -reference section, which explains each of the steps in more detail. +Step-by-step guide on reporting Linux kernel issues +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =20 -Note: this section covers a few more aspects than the TL;DR and does thing= s in -a slightly different order. That's in your interest, to make sure you noti= ce -early if an issue that looks like a Linux kernel problem is actually cause= d by -something else. These steps thus help to ensure the time you invest in this -process won't feel wasted in the end: +Note: Only the steps starting with '*you must*' are strictly required -- b= ut +following the others is usually in your own interest. =20 * Are you facing an issue with a Linux kernel a hardware or software vend= or provided? Then in almost all cases you are better off to stop reading t= his --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3E6822DAFA2; Sun, 26 Oct 2025 12:42:32 +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=1761482555; cv=none; b=EiF3yqISQHrdwe3GW/tR0yT3kk2N6ssxw5eECdkrQRxU0uKkPcq5FjMH9rd9pScma8yOnIAUdsPQikNyjEpfDqRddSC43JPS39GUWfjGgXHowc1KP2lDwNQi1+Cr1kBG4WLrNB2c3fthQqm88jFgi11AIv30gR/IWT1zFXd5gaQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482555; c=relaxed/simple; bh=mIfOql5N32gMBe8X0YcC5hGJmUeX5bAGGFy1Owp4xsQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=X2ZwVbb9yEe7RFVoIY0GEiRFgTGn/ZqM9QrtjMS0MD/pSYuBRvlDyKBCINbKKF8QaUdsrOsZdyrnpwPAQSM+Lpuuy4XaZRgztLLBCQeSB6NZGpy5WkP/QfZ/uXdD4+MOXSrwL/xSiWZpfqkszAdfzQQ21fZEjMf+SdD1sncqiLc= 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=2Axv5OB4; 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="2Axv5OB4" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=leemhuis.info; s=he214686; h=Content-Transfer-Encoding:Content-Type: 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=CSmPZuTVU5I53EMM1NfC1a+zinZRXjBZwbdJiYWrI/k=; t=1761482552; x=1761914552; b=2Axv5OB4hhu0eXwgpTOeu3zO1ZS5QyqJAq/gW/ecv3Uu1blQpKjyoalFSjJ6T jULiqpa/wFa+r7xtYHzIZ9cMS00jY4THu/Cmb2mAqYCXssc4s1RGE2u7bf+4Wdt8nqtuNFZrWVk1S PzDpX7NacLOBVaa1VOm6kY00xV3VPGJVcNxFKVLLfmtZblIeXnYOFg7QjycEMLCS4jWf32KsfwSKd Qj9Sgnv4NROzh6I5ac592DcXzOqfjMkLW13BKwJRLYhrVr9MZoNDl3ef0kF4Hrjap0z52oLD58smT tOqM4T/Vaox42GlDMXP/DwBMLClalBmhxV1qjz/ppmwSMFJ61g==; 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 1vD04m-001mXP-2z; Sun, 26 Oct 2025 13:42:24 +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 07/30] docs: reporting-issues: explain need for fresh vanilla kernel Date: Sun, 26 Oct 2025 13:41:58 +0100 Message-ID: <616e01c3b2212e3dc7c7cc40f551618092f40c62.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-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1761482552;81a32109; X-HE-SMSGID: 1vD04m-001mXP-2z Rewrite the section that explains why a fresh kernel is needed and why bug reporters might have to compile one themselves for testing and debugging purposes. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 141 +++++++++++------- 1 file changed, 85 insertions(+), 56 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 7dfb3ca4b3e322..2f387e8766f21d 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -49,11 +49,25 @@ Step-by-step guide on reporting Linux kernel issues Note: Only the steps starting with '*you must*' are strictly required -- b= ut following the others is usually in your own interest. =20 - * Are you facing an issue with a Linux kernel a hardware or software vend= or - provided? Then in almost all cases you are better off to stop reading t= his - document and reporting the issue to your vendor instead, unless you are - willing to install the latest Linux version yourself. Be aware the latt= er - will often be needed anyway to hunt down and fix issues. +.. _intro_repisbs: + +* Be aware: + + * You should report issues using a Linux kernel that is both really fres= h and + vanilla. That often means that you will have to remove software that + requires externally developed kernel modules and install the newest up= stream + Linux development kernel yourself. + + * There is a decent chance you will have to report the problem by email,= in + which case your email address will become part of public archives. + + * You might need to patch and build your own kernel to help developers d= ebug + and fix the bug. + + If these three aspects sound too demanding, consider reporting the issue = to + your Linux distributor or hardware manufacturer instead. + + [:ref:`details `] =20 * Perform a rough search for existing reports with your favorite internet search engine; additionally, check the archives of the `Linux Kernel Ma= iling @@ -265,57 +279,72 @@ With that off the table, find below details for the s= teps from the detailed guide on reporting issues to the Linux kernel developers. =20 =20 -Make sure you're using the upstream Linux kernel ------------------------------------------------- - - *Are you facing an issue with a Linux kernel a hardware or software ven= dor - provided? Then in almost all cases you are better off to stop reading t= his - document and reporting the issue to your vendor instead, unless you are - willing to install the latest Linux version yourself. Be aware the latt= er - will often be needed anyway to hunt down and fix issues.* - -Like most programmers, Linux kernel developers don't like to spend time de= aling -with reports for issues that don't even happen with their current code. It= 's -just a waste everybody's time, especially yours. Unfortunately such situat= ions -easily happen when it comes to the kernel and often leads to frustration o= n both -sides. That's because almost all Linux-based kernels pre-installed on devi= ces -(Computers, Laptops, Smartphones, Routers, =E2=80=A6) and most shipped by = Linux -distributors are quite distant from the official Linux kernel as distribut= ed by -kernel.org: these kernels from these vendors are often ancient from the po= int of -Linux development or heavily modified, often both. - -Most of these vendor kernels are quite unsuitable for reporting issues to = the -Linux kernel developers: an issue you face with one of them might have been -fixed by the Linux kernel developers months or years ago already; addition= ally, -the modifications and enhancements by the vendor might be causing the issu= e you -face, even if they look small or totally unrelated. That's why you should = report -issues with these kernels to the vendor. Its developers should look into t= he -report and, in case it turns out to be an upstream issue, fix it directly -upstream or forward the report there. In practice that often does not work= out -or might not what you want. You thus might want to consider circumventing = the -vendor by installing the very latest Linux kernel core yourself. If that's= an -option for you move ahead in this process, as a later step in this guide w= ill -explain how to do that once it rules out other potential causes for your i= ssue. - -Note, the previous paragraph is starting with the word 'most', as sometimes -developers in fact are willing to handle reports about issues occurring wi= th -vendor kernels. If they do in the end highly depends on the developers and= the -issue in question. Your chances are quite good if the distributor applied = only -small modifications to a kernel based on a recent Linux version; that for -example often holds true for the mainline kernels shipped by Debian GNU/Li= nux -Sid or Fedora Rawhide. Some developers will also accept reports about issu= es -with kernels from distributions shipping the latest stable kernel, as long= as -it's only slightly modified; that for example is often the case for Arch L= inux, -regular Fedora releases, and openSUSE Tumbleweed. But keep in mind, you be= tter -want to use a mainline Linux and avoid using a stable kernel for this -process, as outlined in the section 'Install a fresh kernel for testing' i= n more -detail. - -Obviously you are free to ignore all this advice and report problems with = an old -or heavily modified vendor kernel to the upstream Linux developers. But no= te, -those often get rejected or ignored, so consider yourself warned. But it's= still -better than not reporting the issue at all: sometimes such reports directl= y or -indirectly will help to get the issue fixed over time. +.. _intro_repiref: + +You likely need to compile at least one really fresh kernel +----------------------------------------------------------- + + *Be aware:You should report issues using a Linux kernel that is both rea= lly + fresh and vanilla. [...] Your email address will become part of public + archives [...] You might need to patch and build your own kernel* [:ref:= `... `] + +You most likely will have to fiddle with your setup and install at least o= ne +fresh Linux kernel while reporting the issue or trying to resolve it. The +step-by-step guide mentions a few, but the most important is: + +The kernels most Linux users utilize are unsuitable for reporting bugs +upstream, as the problem might have been fixed already or never happened w= ith +the upstream code in the first place. Such situations occur frequently whe= n it +comes to Linux: + +1. Many developers consider all 'longterm' (aka 'LTS') kernels as too old = and + thus unsuitable for reporting, except for series-specific regressions (= say + from 6.1.13 to 6.1.15) in still-supported series (see `frontpage of + kernel.org `_). Reporting using the newest version= from + the latest 'stable' series can work -- but some developers only take a + closer look at bugs reported using a fresh mainline kernel, as the bug = might + have been fixed already. + +2. Almost all Linux-based kernels pre-installed on devices (computers, lap= tops, + smartphones, routers, =E2=80=A6) are therefore too old as well, but eve= n when not, + often unsuitable for a second reason: + + Most vendors modify Linux's source code (some heavily!) before building = their + kernels; frequently their kernels also load externally developed modules + ('out-of-tree drivers'), too. Such modifications or enhancements might be + causing your issue, even when they seem tiny and unrelated. Upstream + developers can do nothing about such problems. + + You therefore have to report issues with such kernels to the vendor. Its + developers should look into the report and, in case it turns out to be an + upstream issue, report or directly fix it there. In practice that often = does + not work out or might not be what you want; installing your own fresh va= nilla + kernel while steering clear of externally developed modules is your way = out + here. + +Note: Some developers, despite the aforementioned aspects, are willing to = handle +reports about issues in kernels that are somewhat older or slightly diverg= ed. +If they will highly depends on the circumstances: + +* Your chances are quite good if the vendor performed only small changes t= o a + recent mainline codebase; that, for example, often holds true for the ke= rnels + shipped by Debian GNU/Linux Sid (aka 'unstable') or Fedora Rawhide. + +* Chances are slightly worse but still relatively good for reports about i= ssues + with the newest version from the latest Linux stable series. That is the= case + even when the distributor slightly modified or enhanced the kernel's cod= e -- + this, for example, is often the case for the default kernels of Arch Lin= ux and + openSUSE Tumbleweed, as well as regular Fedora releases when using the l= atest + stable series. + +You are free to ignore this advice and report problems to the upstream Lin= ux +developers occurring with kernels that are outdated, modified, or utilizing +out-of-tree drivers. But be aware that developers might react coldly or ne= ver +at all. Nevertheless, it is still better than not reporting the issue: +sometimes such a report directly or indirectly helps to resolve issues over +time. + +[:ref:`back to step-by-step guide `] =20 =20 Search for existing reports, first run --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3E0832DA774; Sun, 26 Oct 2025 12:42:32 +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=1761482554; cv=none; b=KnR2pGNPSN9Z9kQcmWNVXi64YP42X3OeCDi6eSQPKizQaVoQtiTeEBVvqr6vfN3V3IW1toz08mO/pYJ1x/GqQTxfkCbhJMN8g+UfifxLWvP6X2w5RHTTnhVLNLM2jYe0Mlo73kUzhmT1mGBlsMTIfZ2/H22yzG5gpkqHEMhVDLw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482554; c=relaxed/simple; bh=MzQ28r/dhKKX8TM4X+PZrQvHqruMDwFGroswwwsys9Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=q1FnU2YidmPL7ENumIgStOwIYgbI9dhZSUj/bLV8vOh2G7ewdc+cxhDKKTxEclL1+ZynAY4j7yhLkTiQUESoADR+TbFZ5x3LM1soLt/97pDHE+VoOYcP/35HzxA048TGbTEj4tWdSVLCNXsWUagCqqCe/kLO3aZUSsrtzow5pr8= 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=2LjgI+Li; 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="2LjgI+Li" 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=pErYh5HOsLK9BdZsfpbPa+r/6tDB+XJBSgvlVnQBtUI=; t=1761482552; x=1761914552; b=2LjgI+LixOHDAk69lv8VHy1dvs69ckQrKkbienw8DcLhOVgz5wYcwCkwfDcZN KUgcyP1ppE/v7aCfQ/ZD5kVU5oVQ1exQDovA2bBk31SdNeMyXap5kEd4xJCwZtDK6YD8CVXHK70ga sC+N9COKxP7Sypwba+JX2QLFcTxKrXu8JQW8NVZn9IfrPcYhhpg3hzLZuU9chqgw7l39glASVJzJG rno7zXKM5RafRrnklHRvBhVruTWDTgO5c7iG23ecOaFZgNKYFX0Thxt2R0NIxrKZzLAigIhy/QFiU OkGmywcsAEfYHpgdh7h2TC4b+LdfBru2Gd6lz1Fsc6OumDzrsQ==; 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 1vD04n-001mXP-0f; Sun, 26 Oct 2025 13:42:25 +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 08/30] docs: reporting-issues: add step about processing issues separately Date: Sun, 26 Oct 2025 13:41:59 +0100 Message-ID: <9b6e279c9d11eefe7ff01672a054783dbf651bc0.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;1761482552;81a32109; X-HE-SMSGID: 1vD04n-001mXP-0f Content-Type: text/plain; charset="utf-8" Create a separate step covering 'process and report each separately if you deal with multiple issues at the same time'. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 45 ++++++++++++------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 2f387e8766f21d..73b7792d84cdf1 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -69,6 +69,14 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 +.. _multiple_repisbs: + +* *You must* process and report each issue separately if you deal with mul= tiple. + If there is a slim chance they are related, remember to briefly mention = the + other problems in each of the reports, ideally cross-linking them in the= end. + + [:ref:`details `] + * Perform a rough search for existing reports with your favorite internet search engine; additionally, check the archives of the `Linux Kernel Ma= iling List (LKML) `_. If you find matching rep= orts, @@ -90,11 +98,7 @@ following the others is usually in your own interest. * Check if your kernel was 'tainted' when the issue occurred, as the event that made the kernel set this flag might be causing the issue you face. =20 - * Write down coarsely how to reproduce the issue. If you deal with multip= le - issues at once, create separate notes for each of them and make sure th= ey - work independently on a freshly booted system. That's needed, as each i= ssue - needs to get reported to the kernel developers separately, unless they = are - strongly entangled. + * Write down coarsely how to reproduce the issue. =20 * If you are facing a regression within a stable or longterm version line (say something broke when updating from 5.10.4 to 5.10.5), scroll down = to @@ -347,6 +351,23 @@ time. [:ref:`back to step-by-step guide `] =20 =20 +.. _multiple_repiref: + +Issues must be reported one by one +---------------------------------- + + *You must process and report each issue separately if you deal with + multiple. If there is a slim chance* [:ref:`... `] + +You will have to report issues one by one if you deal with multiple, as th= ey +likely will be handled by different developers; describing various issues = in +one report also makes it difficult for others to understand the situation. +Hence, only combine issues in one report if they are very strongly +entangled or clearly have the same cause. + +[:ref:`back to step-by-step guide `] + + Search for existing reports, first run -------------------------------------- =20 @@ -569,19 +590,9 @@ three things: Document how to reproduce issue ------------------------------- =20 - *Write down coarsely how to reproduce the issue. If you deal with mult= iple - issues at once, create separate notes for each of them and make sure t= hey - work independently on a freshly booted system. That's needed, as each = issue - needs to get reported to the kernel developers separately, unless they= are - strongly entangled.* - -If you deal with multiple issues at once, you'll have to report each of th= em -separately, as they might be handled by different developers. Describing -various issues in one report also makes it quite difficult for others to t= ear -it apart. Hence, only combine issues in one report if they are very strong= ly -entangled. + *Write down coarsely how to reproduce the issue.* =20 -Additionally, during the reporting process you will have to test if the is= sue +During the reporting process you will have to test if the issue happens with other kernel versions. Therefore, it will make your work easi= er if you know exactly how to reproduce an issue quickly on a freshly booted sys= tem. =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3DFDB2D97A1; Sun, 26 Oct 2025 12:42:32 +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=1761482555; cv=none; b=OaTv8WjQDcYHn/+pRUVPH6mB0ics6LUtYtLOP5hLo8YAdbpTVlBW5QjFkhpy7PfFGAY1KgVmF5vjpnEoF7b4Ru/i6AB+2p611gEz0/f6K7lTF5rArytXR1kCpAoIAVyn4p7dO2EiOpDQeYPx+cblR78Fd9yNVopBvOs8j7Ho1Ys= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482555; c=relaxed/simple; bh=v3EcZfTQH9yUaeLOyiACtSLQBw4OfVXYTDSPYRHxRtA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=RUiTxN6uqQSNjEl+H/EonXI7pqEkbzlXudI191M9WCA2ZN8FkDT+GdCQUwqDYgW6Ctg3BeuX7CItlRAECryuPiziySO5awsXX3ci1QrxHjTR4Zpdda+QGwvyTsp8+PNpPJJtRfE/1NEVtoFwMhykagMTJ5Rad8qccVkeW1PDMtI= 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=BsvtbpIR; 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="BsvtbpIR" 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=1lpe93ywVbepQX5TMSIxLuqlkD6WIX6nms0KuNBW1jE=; t=1761482552; x=1761914552; b=BsvtbpIRcESSr/nD5yaH/WqU2nrd57K96YrH+cPYJb0Ub2a1Elau5SyfxZPDl QpHqw8Bl0100Cqzl4X0IKXklDQsd/pLvnQrzF83GQktFycsvbeL5K3WLQ8T2Fbkf/OWEDYVKzd9ny PVKG5DNOunRQIssu2C7AIgAo9G763Aej+L7c++WSdtJ0EWqAwvzr1Ok+TCyI4MZlpXYvNlNhMpUeS U9RusVAjfofcsehyIhSwhfPFHZMhzrqE6/SVfKAj09OV0roJQ3sIhqlXx+oZbIJ6PthmNIzfkobjM 4zEi4DwVCh/zzaFv3da10+InGamUVFfZKpgr1MOs3IfwziCSRg==; 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 1vD04n-001mXP-1b; Sun, 26 Oct 2025 13:42:25 +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 09/30] docs: reporting-issues: tell users to check the kernel log Date: Sun, 26 Oct 2025 13:42:00 +0100 Message-ID: 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;1761482552;81a32109; X-HE-SMSGID: 1vD04n-001mXP-1b Content-Type: text/plain; charset="utf-8" Sometimes what looks like a kernel bug is actually some local problem the kernel's log messages explain, thus it is best if users check it early in the process. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 73b7792d84cdf1..63ce6ae51df266 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -77,6 +77,14 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 +.. _checklog_repisbs: + +* Skim ``journalctl -k`` (alternatively: ``dmesg``) for failures and warni= ngs, + as maybe there is just something wrong with your setup. + + [:ref:`details `] + + * Perform a rough search for existing reports with your favorite internet search engine; additionally, check the archives of the `Linux Kernel Ma= iling List (LKML) `_. If you find matching rep= orts, @@ -368,6 +376,27 @@ entangled or clearly have the same cause. [:ref:`back to step-by-step guide `] =20 =20 +.. _checklog_repiref: + +Evaluate the logs +----------------- + + *Skim 'journalctl -k' (alternatively: 'dmesg') for failures and warnings= , as + maybe there is just something wrong with your setup.* [:ref:`... `] + +Sometimes a bug you face is just a symptom of something going sideways tha= t the +kernel detected and logged -- like a missing firmware file, for example. T= o rule +such things out, check the kernel's log messages. + +Preferably use 'journalctl' if your distribution supports it, as in contra= st to +'dmesg' it always contains all messages since the kernel started. + +Especially look out for messages in bold, yellow, or red, as both tools us= e such +to set warnings and errors apart. + +[:ref:`back to step-by-step guide `] + + Search for existing reports, first run -------------------------------------- =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3E3B12DC766; Sun, 26 Oct 2025 12:42:33 +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=1761482557; cv=none; b=kJaRE8GaG5RXc9pLp+anChu/GZG7rj12E9iCVNJv5sDe2KisVD0JfvVbVZC3wqk32z5igSmMur4AewYGFO1dOAuvUVpEpImr/jUbKD4vDBvgWKgV9eOtKa3XuCR4ADHWCYnWKhlTrgT6N0ZKGQEZqiGl44dMxWDEjEe3C/hjpD8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482557; c=relaxed/simple; bh=517i2jj1FP1eA4gNNSFn+t3wDqkwPadIwOLbp+tJV7k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=tKrPyDlmH6pt1aHcmKgBNHggOD6tFn6PHxeEG3CT7/5j9+a4gOvLZ6Ogs69ACVVhC6c9VaF6LhbY3UKycdqXEJODPZwGlpY8N6ItBdP/kXJznXj6ItSDe6HFOSlmWDTgdyYwKsQjLDIJvlsC48fXFokftiOuQdd3qKkPwYNyAWA= 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=bYzu/IjO; 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="bYzu/IjO" 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=3sCIFxfR/3bAfkz3RVepSUlcaCv5Ie7/jvVe7/s8Bmk=; t=1761482553; x=1761914553; b=bYzu/IjO7C+LbBcj1+dDUSDS0+KtbTHc3tmNsN7cWczmZyMTb/0ztGNQbePb/ T9gdo71iJrUGyJdtOUGoiZeXGXbZnpCFHBQPFAyZ6SDH45rBtaI9iu1ytXWRbhbfwf3KMXQBUczMj e7Us1NOivOeUE41Tv3zV8PAnYFBHXrHPfbJjX1c9jeis5sbhX4cS/BDGZJiJj+9n8u4Slqso2R5rp 3CxPzwa1MkhcvEQe/9LT9xRl91oA/7a7bYyapJFCyf/FCusR/YEJCHdJ2YXmBeG0Tsbqd3dZR12Qg M9LcseMthhZJNwrO+2zYaUMGH9ZAUXeEEDmPClYdosLB+Xeavg==; 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 1vD04o-001mXn-0J; Sun, 26 Oct 2025 13:42:26 +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 10/30] docs: reporting-issues: move 'check tainted flag' upwards Date: Sun, 26 Oct 2025 13:42:01 +0100 Message-ID: <93cac5463d1e51b57b7cf74181397039137bcdb5.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;1761482553;4a80bc7e; X-HE-SMSGID: 1vD04o-001mXn-0J Content-Type: text/plain; charset="utf-8" Move text around to improve diffability in the follow-up patch. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 142 +++++++++--------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 63ce6ae51df266..19f1ffabf5ae30 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -85,6 +85,9 @@ following the others is usually in your own interest. [:ref:`details `] =20 =20 + * Check if your kernel was 'tainted' when the issue occurred, as the event + that made the kernel set this flag might be causing the issue you face. + * Perform a rough search for existing reports with your favorite internet search engine; additionally, check the archives of the `Linux Kernel Ma= iling List (LKML) `_. If you find matching rep= orts, @@ -103,9 +106,6 @@ following the others is usually in your own interest. kernel modules on-the-fly, which solutions like DKMS might be doing loc= ally without your knowledge. =20 - * Check if your kernel was 'tainted' when the issue occurred, as the event - that made the kernel set this flag might be causing the issue you face. - * Write down coarsely how to reproduce the issue. =20 * If you are facing a regression within a stable or longterm version line @@ -397,6 +397,74 @@ to set warnings and errors apart. [:ref:`back to step-by-step guide `] =20 =20 +Check 'taint' flag +------------------ + + *Check if your kernel was 'tainted' when the issue occurred, as the ev= ent + that made the kernel set this flag might be causing the issue you face= .* + +The kernel marks itself with a 'taint' flag when something happens that mi= ght +lead to follow-up errors that look totally unrelated. The issue you face m= ight +be such an error if your kernel is tainted. That's why it's in your intere= st to +rule this out early before investing more time into this process. This is = the +only reason why this step is here, as this process later will tell you to +install the latest mainline kernel; you will need to check the taint flag = again +then, as that's when it matters because it's the kernel the report will fo= cus +on. + +On a running system is easy to check if the kernel tainted itself: if ``cat +/proc/sys/kernel/tainted`` returns '0' then the kernel is not tainted and +everything is fine. Checking that file is impossible in some situations; t= hat's +why the kernel also mentions the taint status when it reports an internal +problem (a 'kernel bug'), a recoverable error (a 'kernel Oops') or a +non-recoverable error before halting operation (a 'kernel panic'). Look ne= ar +the top of the error messages printed when one of these occurs and search = for a +line starting with 'CPU:'. It should end with 'Not tainted' if the kernel = was +not tainted when it noticed the problem; it was tainted if you see 'Tainte= d:' +followed by a few spaces and some letters. + +If your kernel is tainted, study Documentation/admin-guide/tainted-kernels= .rst +to find out why. Try to eliminate the reason. Often it's caused by one the= se +three things: + + 1. A recoverable error (a 'kernel Oops') occurred and the kernel tainted + itself, as the kernel knows it might misbehave in strange ways after t= hat + point. In that case check your kernel or system log and look for a sec= tion + that starts with this:: + + Oops: 0000 [#1] SMP + + That's the first Oops since boot-up, as the '#1' between the brackets = shows. + Every Oops and any other problem that happens after that point might b= e a + follow-up problem to that first Oops, even if both look totally unrela= ted. + Rule this out by getting rid of the cause for the first Oops and repro= ducing + the issue afterwards. Sometimes simply restarting will be enough, some= times + a change to the configuration followed by a reboot can eliminate the O= ops. + But don't invest too much time into this at this point of the process,= as + the cause for the Oops might already be fixed in the newer Linux kernel + version you are going to install later in this process. + + 2. Your system uses a software that installs its own kernel modules, for + example Nvidia's proprietary graphics driver or VirtualBox. The kernel + taints itself when it loads such module from external sources (even if + they are Open Source): they sometimes cause errors in unrelated kernel + areas and thus might be causing the issue you face. You therefore have= to + prevent those modules from loading when you want to report an issue to= the + Linux kernel developers. Most of the time the easiest way to do that i= s: + temporarily uninstall such software including any modules they might h= ave + installed. Afterwards reboot. + + 3. The kernel also taints itself when it's loading a module that resides = in + the staging tree of the Linux kernel source. That's a special area for + code (mostly drivers) that does not yet fulfill the normal Linux kernel + quality standards. When you report an issue with such a module it's + obviously okay if the kernel is tainted; just make sure the module in + question is the only reason for the taint. If the issue happens in an + unrelated area reboot and temporarily block the module from being load= ed + by specifying ``foo.blacklist=3D1`` as kernel parameter (replace 'foo'= with + the name of the module in question). + + Search for existing reports, first run -------------------------------------- =20 @@ -548,74 +616,6 @@ module not part of the Linux kernel. That why your mig= ht need to uninstall the packages with such software to get rid of any 3rd party kernel module. =20 =20 -Check 'taint' flag ------------------- - - *Check if your kernel was 'tainted' when the issue occurred, as the ev= ent - that made the kernel set this flag might be causing the issue you face= .* - -The kernel marks itself with a 'taint' flag when something happens that mi= ght -lead to follow-up errors that look totally unrelated. The issue you face m= ight -be such an error if your kernel is tainted. That's why it's in your intere= st to -rule this out early before investing more time into this process. This is = the -only reason why this step is here, as this process later will tell you to -install the latest mainline kernel; you will need to check the taint flag = again -then, as that's when it matters because it's the kernel the report will fo= cus -on. - -On a running system is easy to check if the kernel tainted itself: if ``cat -/proc/sys/kernel/tainted`` returns '0' then the kernel is not tainted and -everything is fine. Checking that file is impossible in some situations; t= hat's -why the kernel also mentions the taint status when it reports an internal -problem (a 'kernel bug'), a recoverable error (a 'kernel Oops') or a -non-recoverable error before halting operation (a 'kernel panic'). Look ne= ar -the top of the error messages printed when one of these occurs and search = for a -line starting with 'CPU:'. It should end with 'Not tainted' if the kernel = was -not tainted when it noticed the problem; it was tainted if you see 'Tainte= d:' -followed by a few spaces and some letters. - -If your kernel is tainted, study Documentation/admin-guide/tainted-kernels= .rst -to find out why. Try to eliminate the reason. Often it's caused by one the= se -three things: - - 1. A recoverable error (a 'kernel Oops') occurred and the kernel tainted - itself, as the kernel knows it might misbehave in strange ways after t= hat - point. In that case check your kernel or system log and look for a sec= tion - that starts with this:: - - Oops: 0000 [#1] SMP - - That's the first Oops since boot-up, as the '#1' between the brackets = shows. - Every Oops and any other problem that happens after that point might b= e a - follow-up problem to that first Oops, even if both look totally unrela= ted. - Rule this out by getting rid of the cause for the first Oops and repro= ducing - the issue afterwards. Sometimes simply restarting will be enough, some= times - a change to the configuration followed by a reboot can eliminate the O= ops. - But don't invest too much time into this at this point of the process,= as - the cause for the Oops might already be fixed in the newer Linux kernel - version you are going to install later in this process. - - 2. Your system uses a software that installs its own kernel modules, for - example Nvidia's proprietary graphics driver or VirtualBox. The kernel - taints itself when it loads such module from external sources (even if - they are Open Source): they sometimes cause errors in unrelated kernel - areas and thus might be causing the issue you face. You therefore have= to - prevent those modules from loading when you want to report an issue to= the - Linux kernel developers. Most of the time the easiest way to do that i= s: - temporarily uninstall such software including any modules they might h= ave - installed. Afterwards reboot. - - 3. The kernel also taints itself when it's loading a module that resides = in - the staging tree of the Linux kernel source. That's a special area for - code (mostly drivers) that does not yet fulfill the normal Linux kernel - quality standards. When you report an issue with such a module it's - obviously okay if the kernel is tainted; just make sure the module in - question is the only reason for the taint. If the issue happens in an - unrelated area reboot and temporarily block the module from being load= ed - by specifying ``foo.blacklist=3D1`` as kernel parameter (replace 'foo'= with - the name of the module in question). - - Document how to reproduce issue ------------------------------- =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3A7E42DC76B; Sun, 26 Oct 2025 12:42:33 +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=1761482555; cv=none; b=dMh9Js+YcpFzoO1LlOcaroSHC4HB4R2h3KkI6HtfauDmJtjKgNsnsHhPPxJ7LDRcxgwv82jrp34iZFT3RB2rB9PhqJ4ZvlCuKuy1U7zXzOTzL+x/ngTTp+xm9bXaeKg9s1AwfyGsNONAFbKrIWUosuCL+T1KIo4D6R2jh0kyq48= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482555; c=relaxed/simple; bh=9RlaPYJbqiM2OFxkSIEpzf6QXLP5GS9MehP4KTaVRHk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=NdcvjDV+Fgd4sZHIdU1+YhyTLe7+MibZPQnmRYqOdWI/IW2uaXQvw5UDQvdSLKw0nvTKZVSayE1TDXYBQlbZahGv9iZhumKt2NCTQW9/XKFR7Xet93hFzYOaBf/pwdY8Biv8zBJ4MEPiTzRBfX1NN+aixNxKqA2PaKAPFRqZKDE= 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=WcBO4AJO; 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="WcBO4AJO" 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=OVOHoODjbTBKiS2pRJUZZiaxPXulh2JYJvHA1xkr8fg=; t=1761482553; x=1761914553; b=WcBO4AJOs80Vd0tFMCNg6QkVZIG5ez0L+koWej9CyeeBguc94J7PNxG+er6oS DummpkRzWoIPuSm8oTX28GWdJPU4eouXAzy2SvP18Spz4Z1Q1vJJqLtGd1cOJ5MW4Eaqg2bc6uJNv HgaXxksUOsy6EtpULz4vlVcPwKNinRJeITlCv2FK4mu2MOIBzCJAc1waC3ME1yOpCl7fKajurEeAP QgUmN/LpBJx/2BzZ0i63MlgFrgXRA7Zxfw1smPMKcI9lNpJTF0Xfr2NI4qR0Rn2txyPqmUNtpP0e4 jIaRH29PXXUuaMj+kTOlh/6V7hULYLu29WGEu0jkNyLxiLS9qw==; 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 1vD04o-001mXn-1a; Sun, 26 Oct 2025 13:42:26 +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 11/30] docs: reporting-issues: improve first tainted check Date: Sun, 26 Oct 2025 13:42:02 +0100 Message-ID: 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;1761482553;4a80bc7e; X-HE-SMSGID: 1vD04o-001mXn-1a Content-Type: text/plain; charset="utf-8" Fine-tune the instruction regarding the first tainted check. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 136 ++++++++++-------- 1 file changed, 76 insertions(+), 60 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 19f1ffabf5ae30..452733669debf5 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -84,9 +84,14 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 +.. _taintone_repisbs: + +* Check if the kernel was already 'tainted' when the issue first occurred:= The + event that resulted in this flag being set might have led to issues that + otherwise would never happen. + + [:ref:`details `] =20 - * Check if your kernel was 'tainted' when the issue occurred, as the event - that made the kernel set this flag might be causing the issue you face. =20 * Perform a rough search for existing reports with your favorite internet search engine; additionally, check the archives of the `Linux Kernel Ma= iling @@ -397,72 +402,83 @@ to set warnings and errors apart. [:ref:`back to step-by-step guide `] =20 =20 +.. _taintone_repiref: + Check 'taint' flag ------------------ =20 - *Check if your kernel was 'tainted' when the issue occurred, as the ev= ent - that made the kernel set this flag might be causing the issue you face= .* + *Check if the kernel was already 'tainted' when the issue first occurred= * [:ref:`... `] =20 The kernel marks itself with a 'taint' flag when something happens that mi= ght -lead to follow-up errors that look totally unrelated. The issue you face m= ight -be such an error if your kernel is tainted. That's why it's in your intere= st to -rule this out early before investing more time into this process. This is = the -only reason why this step is here, as this process later will tell you to -install the latest mainline kernel; you will need to check the taint flag = again -then, as that's when it matters because it's the kernel the report will fo= cus -on. - -On a running system is easy to check if the kernel tainted itself: if ``cat -/proc/sys/kernel/tainted`` returns '0' then the kernel is not tainted and -everything is fine. Checking that file is impossible in some situations; t= hat's -why the kernel also mentions the taint status when it reports an internal -problem (a 'kernel bug'), a recoverable error (a 'kernel Oops') or a -non-recoverable error before halting operation (a 'kernel panic'). Look ne= ar -the top of the error messages printed when one of these occurs and search = for a -line starting with 'CPU:'. It should end with 'Not tainted' if the kernel = was -not tainted when it noticed the problem; it was tainted if you see 'Tainte= d:' -followed by a few spaces and some letters. - -If your kernel is tainted, study Documentation/admin-guide/tainted-kernels= .rst -to find out why. Try to eliminate the reason. Often it's caused by one the= se -three things: - - 1. A recoverable error (a 'kernel Oops') occurred and the kernel tainted - itself, as the kernel knows it might misbehave in strange ways after t= hat - point. In that case check your kernel or system log and look for a sec= tion - that starts with this:: +lead to follow-up errors looking totally unrelated. Your issue might +be such an error, in which case there is nothing to report. That is why it= is +in your interest to check the taint status early in the reporting process.= This +is the main reason why this step is here in the guide, as you most likely = will +have to install a different kernel for reporting later -- and then need to +recheck the flag, as that is when it matters. + +To check the tainted flag, execute ``cat /proc/sys/kernel/tainted``: If it +returns '0' everything is fine; if it contains a higher number, it is tain= ted. + +In some situations it is impossible to check that file. That is +why the kernel also mentions the taint status when it reports small (a +'warning' or a 'bug') or big (an 'Oops' or a 'panic') problems. In such ca= ses, +search for a line starting with 'CPU:' near the top of the error messages +printed on the screen or in the log. If the kernel at that point considered +itself to be fine, it will end with 'Not tainted'; if not, you will see +'Tainted:' followed by a few spaces and some letters. + +If your kernel is tainted, check Documentation/admin-guide/tainted-kernels= .rst +to find out why. Note: It is quite possible that the problem you ran into +caused the kernel to taint itself, in which case you are free to ignore the +flag. But if the kernel was tainted beforehand, you might have to eliminat= e the +cause or rule out that it is an influence. + +These are the most frequent reasons why the kernel set the flag: + +1. Some kind of error (like a 'kernel Oops') occurred. The kernel then tai= nts + itself, as it might misbehave in unexpected ways afterwards. + In that case check your kernel or system log and look for a section + starting with:: =20 Oops: 0000 [#1] SMP =20 - That's the first Oops since boot-up, as the '#1' between the brackets = shows. - Every Oops and any other problem that happens after that point might b= e a - follow-up problem to that first Oops, even if both look totally unrela= ted. - Rule this out by getting rid of the cause for the first Oops and repro= ducing - the issue afterwards. Sometimes simply restarting will be enough, some= times - a change to the configuration followed by a reboot can eliminate the O= ops. - But don't invest too much time into this at this point of the process,= as - the cause for the Oops might already be fixed in the newer Linux kernel - version you are going to install later in this process. - - 2. Your system uses a software that installs its own kernel modules, for - example Nvidia's proprietary graphics driver or VirtualBox. The kernel - taints itself when it loads such module from external sources (even if - they are Open Source): they sometimes cause errors in unrelated kernel - areas and thus might be causing the issue you face. You therefore have= to - prevent those modules from loading when you want to report an issue to= the - Linux kernel developers. Most of the time the easiest way to do that i= s: - temporarily uninstall such software including any modules they might h= ave - installed. Afterwards reboot. - - 3. The kernel also taints itself when it's loading a module that resides = in - the staging tree of the Linux kernel source. That's a special area for - code (mostly drivers) that does not yet fulfill the normal Linux kernel - quality standards. When you report an issue with such a module it's - obviously okay if the kernel is tainted; just make sure the module in - question is the only reason for the taint. If the issue happens in an - unrelated area reboot and temporarily block the module from being load= ed - by specifying ``foo.blacklist=3D1`` as kernel parameter (replace 'foo'= with - the name of the module in question). + That is the first Oops since boot-up, as the '#1' between the brackets = shows. + Every later Oops and any other problem that happens afterwards might be + a follow-up issue + that would never have happened otherwise, even if both look totally unr= elated. + Rule this out by eliminating the cause for the first Oops and reproduci= ng + the issue afterwards. Sometimes simply restarting will be enough; other= times + a change to the configuration followed by a reboot can eliminate the Oo= ps. + + Note: Do not invest too much time into this while you are still on an + outdated or vendor kernel: The cause for the Oops might already be fixe= d in + a newer Linux kernel + version you most likely will have to install for reporting while follow= ing + this guide. + +2. Your system uses software that installs externally developed kernel mod= ules, + for example, kernel modules from Nvidia, OpenZFS, VirtualBox, or VMware= . The + kernel taints itself when it loads such 'out-of-tree' modules -- no mat= ter + what license they use, as such modules can cause errors in unrelated ke= rnel + areas and thus might be leading to the issue you face. You therefore ha= ve to + prevent those modules from loading when you want to report an issue to = the + Linux kernel developers. Most of the time the easiest way to do that: + temporarily uninstall such software including any modules they might ha= ve + installed; afterwards reboot. + +3. The kernel taints itself when it loads a module that resides in + the staging section of the Linux kernel source. That is a special area = for + code (mostly drivers) that does not yet fulfill the normal Linux kernel + quality standards. When you report an issue with such a module, it is + totally okay if the kernel is tainted; just make sure the module in + question is the only reason for the taint. If the issue happens in an + unrelated area, it is wise to rule out that it is an influence. To do s= o, + reboot and temporarily block the module from being loaded by specifying + ``foo.blacklist=3D1`` as kernel boot parameter (replace 'foo' with the = name of + the module in question). + +[:ref:`back to step-by-step guide `] =20 =20 Search for existing reports, first run --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3D21A2DCF5B; Sun, 26 Oct 2025 12:42:34 +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=1761482557; cv=none; b=bcwmG9V0xSWznEFsJXSiUM9kOOXGIwaXHmhbAGKCTqElnBaTkE4OZJYOA42nWVUg7L467MA16n/dwaiwuyuHwZ3lFtEyRoVDmAMtHgBM4HXlY6k/mfgLaQf2RfuMtyOK1Xp7MHHF67SlivIVrhP2MEMnhl/N+YJlMaTmiqCPUdU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482557; c=relaxed/simple; bh=gOfqGvqqIFHcQUAZGpfPCA8S3+jH7XYY2zmzOE4CeME=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=UQ8o4TOjHx294f+BbMXDabJ8eaIgBXy70rwEwclrBf7fJAjc6l4vEvcoQNmVjGHRYjuxqZnxqRZZluoOebYfghY4lyK6k1L+PKXTjYboCIIOngAuIesVwiNr4LUIzNEwGIFZx1yniIO/xpKHyhYGw7L7QExYL8UY4o8xnTYitgg= 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=x/AwPDbE; 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="x/AwPDbE" 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=cMBWfq9UPEX71weT6EaVXza2Wgm0L5xENSgTv1nRzqE=; t=1761482554; x=1761914554; b=x/AwPDbEKR9BYItc/yaSl9YmhlIz7rgVNpiv3gh/Kffco0mDse3BtEQ/eNzVs A82GGcqcfHETB2BOuVhZRjy078A7dE4lfwylMmBHQBkmIJi9rk+NlvOYpymYLIyPSYOsem99AjV2W y0zNwblCm7Gc7uyDpAKxx6iV362nnRgDrzfcGiQEhQEM76r42bdD+oleurB1a1zAsjPO8IsRPF74P g3RYdnopL7Hr326pDY/cA2D39mf5OhojlZmT7cQI4/7xd1TgKzwU1C+YgEpWqWQGpm3QLLwgcY+fH yicdubTuoYR3qBgfBknIvt4In0x3MjBzfVPV4vnV2gZTPY5XwA==; 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 1vD04o-001mXn-2f; Sun, 26 Oct 2025 13:42:26 +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 12/30] docs: reporting-issues: move 'check environment' upwards Date: Sun, 26 Oct 2025 13:42:03 +0100 Message-ID: <2fc7c4a2c721826bc01d6616fe54ed6136362a31.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;1761482554;2f8dc1da; X-HE-SMSGID: 1vD04o-001mXn-2f Content-Type: text/plain; charset="utf-8" Move text around to improve diffability of an follow-up patch. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 76 +++++++++---------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 452733669debf5..861237aaf94126 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -93,6 +93,9 @@ following the others is usually in your own interest. [:ref:`details `] =20 =20 + * Make sure it's not the kernel's surroundings that are causing the issue + you face. + * Perform a rough search for existing reports with your favorite internet search engine; additionally, check the archives of the `Linux Kernel Ma= iling List (LKML) `_. If you find matching rep= orts, @@ -102,9 +105,6 @@ following the others is usually in your own interest. issue, or a really severe problem: those are 'issues of high priority' = that need special handling in some steps that are about to follow. =20 - * Make sure it's not the kernel's surroundings that are causing the issue - you face. - * Create a fresh backup and put system repair and restore tools at hand. =20 * Ensure your system does not enhance its kernels by building additional @@ -481,6 +481,41 @@ These are the most frequent reasons why the kernel set= the flag: [:ref:`back to step-by-step guide `] =20 =20 +Ensure a healthy environment +---------------------------- + + *Make sure it's not the kernel's surroundings that are causing the iss= ue + you face.* + +Problems that look a lot like a kernel issue are sometimes caused by build= or +runtime environment. It's hard to rule out that problem completely, but you +should minimize it: + + * Use proven tools when building your kernel, as bugs in the compiler or = the + binutils can cause the resulting kernel to misbehave. + + * Ensure your computer components run within their design specifications; + that's especially important for the main processor, the main memory, an= d the + motherboard. Therefore, stop undervolting or overclocking when facing a + potential kernel issue. + + * Try to make sure it's not faulty hardware that is causing your issue. B= ad + main memory for example can result in a multitude of issues that will + manifest itself in problems looking like kernel issues. + + * If you're dealing with a filesystem issue, you might want to check the = file + system in question with ``fsck``, as it might be damaged in a way that = leads + to unexpected kernel behavior. + + * When dealing with a regression, make sure it's not something else that + changed in parallel to updating the kernel. The problem for example mig= ht be + caused by other software that was updated at the same time. It can also + happen that a hardware component coincidentally just broke when you reb= ooted + into a new kernel for the first time. Updating the systems BIOS or chan= ging + something in the BIOS Setup can also lead to problems that on look a lot + like a kernel regression. + + Search for existing reports, first run -------------------------------------- =20 @@ -563,41 +598,6 @@ fatal error where the kernel stop itself) with a 'Oops= ' (a recoverable error), as the kernel remains running after the latter. =20 =20 -Ensure a healthy environment ----------------------------- - - *Make sure it's not the kernel's surroundings that are causing the iss= ue - you face.* - -Problems that look a lot like a kernel issue are sometimes caused by build= or -runtime environment. It's hard to rule out that problem completely, but you -should minimize it: - - * Use proven tools when building your kernel, as bugs in the compiler or = the - binutils can cause the resulting kernel to misbehave. - - * Ensure your computer components run within their design specifications; - that's especially important for the main processor, the main memory, an= d the - motherboard. Therefore, stop undervolting or overclocking when facing a - potential kernel issue. - - * Try to make sure it's not faulty hardware that is causing your issue. B= ad - main memory for example can result in a multitude of issues that will - manifest itself in problems looking like kernel issues. - - * If you're dealing with a filesystem issue, you might want to check the = file - system in question with ``fsck``, as it might be damaged in a way that = leads - to unexpected kernel behavior. - - * When dealing with a regression, make sure it's not something else that - changed in parallel to updating the kernel. The problem for example mig= ht be - caused by other software that was updated at the same time. It can also - happen that a hardware component coincidentally just broke when you reb= ooted - into a new kernel for the first time. Updating the systems BIOS or chan= ging - something in the BIOS Setup can also lead to problems that on look a lot - like a kernel regression. - - Prepare for emergencies ----------------------- =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3D6B22DCF5D; Sun, 26 Oct 2025 12:42:34 +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=1761482556; cv=none; b=OwCxxkP/J0sMnouE8ifQLBe2FZdaRwcXQMaErFxMfGELY88la85t4Ly8BVG7SFqkK+qQhyau4VtOE75070QcX95wqCWBAmCvRMuB774rRhJlItpJVxH2mE2KPsPZ8cEyoez1cmFZtMLhfbMdElisQkUZJWRT9RxntIkXqpXso/c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482556; c=relaxed/simple; bh=aN4oTmpwa1enpG9GmHeTbntkM9KkPOpY1JAM1Mzc3/s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=NjhLVwYL9bKSjzZXpsoDmMpIaQYHfx7jfWU5FyIFFHd3OG9PR7BfRMTAbjCU9K3L7mSTQDdOAIKM0NrPc0WJfzfegr5ZDr7nK62wg55Gp2g1o3OxnXSQ4vh1s33NVwdA5bnNrXJyNC0D6FQ70kfbQtnCSutMjZbvekDQYx+rBpY= 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=mLBGvZ0x; 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="mLBGvZ0x" 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=KECSvN3gX56Uge9ltO6cw9IleaALx97sD5id01QLlPo=; t=1761482554; x=1761914554; b=mLBGvZ0xnJ68q4nCNgqgkO9HFCnfouVfJJJGYLNvrKa3jPVMXwaAHt0bS4C4B 9NWXnDAJAwos8OgmMnXI321P4nn3qO2/ZK3K6l5s89T6OIhOfAARL45AfAiE9UX0M48U5K1qoPGGb awnrcodPa/GerhqKIixF8Ceu+f/mzTYQ3J2vIWUYDCtCyO4iYbdyCVtZ61MQDFJ5nctTQbIi4G5PD N2qy6GdVUQTIAXcsgSjs8Npb/y1DdTB64LHcsbnIP3SGxmTpFv0tDDefUtBYIotzQl8Aa76EOu5+b m5LFLolt4j7Zwyf6FFVAks5XZOAHmXCsSE/wn2hbdXxAZleUUQ==; 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 1vD04p-001mXn-0T; Sun, 26 Oct 2025 13:42:27 +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 13/30] docs: reporting-issues: improve environment check Date: Sun, 26 Oct 2025 13:42:04 +0100 Message-ID: <958f8daae33cfc44124ad9cc6579daa417ba0a77.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;1761482554;2f8dc1da; X-HE-SMSGID: 1vD04p-001mXn-0T Content-Type: text/plain; charset="utf-8" Fine-tune the instructions regarding the environment check. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 74 ++++++++++++------- 1 file changed, 46 insertions(+), 28 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 861237aaf94126..439ec52f270167 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -92,9 +92,17 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 +.. _checkenv_repisbs: + +* Evaluate briefly if some glitch in your kernel's environment might make = it + misbehave -- like a hardware defect, an updated system firmware, a + misconfigured BIOS, an overclocked component, a kernel parameter enabling + something unsupported, a broken initramfs, an inconsistent file system, + changes to the linux-firmware files, or some malfunction/misconfiguratio= n in + your Linux distribution. + + [:ref:`details `] =20 - * Make sure it's not the kernel's surroundings that are causing the issue - you face. =20 * Perform a rough search for existing reports with your favorite internet search engine; additionally, check the archives of the `Linux Kernel Ma= iling @@ -481,39 +489,49 @@ These are the most frequent reasons why the kernel se= t the flag: [:ref:`back to step-by-step guide `] =20 =20 -Ensure a healthy environment ----------------------------- +.. _checkenv_repiref: + +Ensure there is nothing wrong with the kernel's surroundings +------------------------------------------------------------ + + *Evaluate briefly if some glitch in your kernel's environment might make= it + misbehave -- like a* [:ref:`... `] + +Problems that look like a kernel issue are sometimes caused by its +surroundings. It is impossible to detect sometimes -- but it is wise to ru= le +out a few common causes before wasting time on a meaningless bug report: + +* When dealing with a regression (e.g., something stopped working or works= worse + after updating the kernel), make sure it is not something else that chan= ged + in parallel. That could be something else you updated at the same time, = like + the BIOS, the boot loader, Mesa, the linux-firmware package, or something + else close to the kernel; but it could also be some change you performed= in + the BIOS setup or your Linux distribution's configuration. + +* Try to make sure the hardware is healthy, as problems with it can result= in a + multitude of issues that look like kernel bugs. =20 - *Make sure it's not the kernel's surroundings that are causing the iss= ue - you face.* + Ideally try to rule out faulty RAM or a dying device causes the problem. =20 -Problems that look a lot like a kernel issue are sometimes caused by build= or -runtime environment. It's hard to rule out that problem completely, but you -should minimize it: + Also ensure your computer components run within their design specificati= ons; + that is especially important for the main processor, the RAM, and the + motherboard. Therefore, stop undervolting or overclocking when facing a + potential kernel issue. =20 - * Use proven tools when building your kernel, as bugs in the compiler or = the - binutils can cause the resulting kernel to misbehave. +* Temporarily remove any optional kernel parameters you use, as they might + enable unsupported or experimental features. =20 - * Ensure your computer components run within their design specifications; - that's especially important for the main processor, the main memory, an= d the - motherboard. Therefore, stop undervolting or overclocking when facing a - potential kernel issue. +* In case of any problems related to booting, check if the initramfs was + generated correctly. =20 - * Try to make sure it's not faulty hardware that is causing your issue. B= ad - main memory for example can result in a multitude of issues that will - manifest itself in problems looking like kernel issues. +* When dealing with a file system issue, check the file + system in question with ``fsck``, as it might be damaged in a way that l= eads + to unexpected kernel behavior. =20 - * If you're dealing with a filesystem issue, you might want to check the = file - system in question with ``fsck``, as it might be damaged in a way that = leads - to unexpected kernel behavior. +* Use proven tools when building your kernel, as bugs in the compiler or t= he + linker can cause the resulting kernel to misbehave. =20 - * When dealing with a regression, make sure it's not something else that - changed in parallel to updating the kernel. The problem for example mig= ht be - caused by other software that was updated at the same time. It can also - happen that a hardware component coincidentally just broke when you reb= ooted - into a new kernel for the first time. Updating the systems BIOS or chan= ging - something in the BIOS Setup can also lead to problems that on look a lot - like a kernel regression. +[:ref:`back to step-by-step guide `] =20 =20 Search for existing reports, first run --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3BFD22DCF58; Sun, 26 Oct 2025 12:42:34 +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=1761482557; cv=none; b=EqcIKWbS2MXmWOp3gkXBCCifggo8xaR+4gCSObFb38zJY3o49HHo6cclgMRVnYx969N6dYDsuaQM/9+Xrvylimv0CjkDOCWap2t9FiqQB5uCcn9cG7PMfo0t8Ite+jwhy4XoMa1qGt3I65i0prs/AuW+zm0fT9ARZtBZeIgcra0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482557; c=relaxed/simple; bh=SxzqtgXnuHp5B/u8BpLyuGH5vp4zglEON7VaEusma0M=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=VIbgjW7aFLgVa9iEq5t38+9ayAQxtPGySmRfNFJPi35b+MwFq40SiplnnDXAYRVuoS0z6izKPp2vLKrYPT/YrMxRgp6kVvyjM7kA0JXWQ/wT8Onx4iS5I0EjzTXX7tizWfA2lRDV8Rm+4BJ2y4wfC9IsioYVukxwc/51KILSHq4= 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=i8IV4Asz; 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="i8IV4Asz" 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=lwoLbJCG/g9rLvqE3zF9jDJz3ge0rUGh/WP0v0I6lRk=; t=1761482554; x=1761914554; b=i8IV4AszYNhghC9pEQvV1O/p4hAhEiBbQmLxdBB3/tNyfRodw5AgLMdmQQ55D 98nk8EGIqPRiZQDaWhY/Z7K05ff0DtHOojgU1B+l7h+XgDzfo/S5mDr8Taxf9c/K5xEmjDtS33Hyo 0oHUZaADMHsk/a0qEX8Un51ywdhlSRDZSKPDf5uFYYOG72vfiQ2K1DXYlcLm4GX7m3exnWy1Ti61f rMaRBTYvZRkNmNsdrlVsoM2Ku+pwXLXKvdKUvLFb7bFs+vgQ56r/i1jtHbaF0LlmCkO3dxUIrVVn6 HoRiD760wRTS7xWjD0I/GQkQklXsoCiL+Uh4Y1nvBbRk9ylTJg==; 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 1vD04p-001mXn-1Q; Sun, 26 Oct 2025 13:42:27 +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 14/30] docs: reporting-issues: improve text about checking for existing issues Date: Sun, 26 Oct 2025 13:42:05 +0100 Message-ID: <3f0a8499e8ee3ae168b9328a0cc5890913cd0635.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;1761482554;2f8dc1da; X-HE-SMSGID: 1vD04p-001mXn-1Q Content-Type: text/plain; charset="utf-8" Fine-tune the instructions with regards to checking for existing issues -- and tell readers straight in the step-by-step guide what to do in slightly more detail. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 166 ++++++++++++------ 1 file changed, 115 insertions(+), 51 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 439ec52f270167..623feb55caae97 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -103,11 +103,31 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 +.. _checkloreone_repisbs: + +* Search `lore `_ for similar reports and + potential fixes; afterwards the wider internet, too. + + If you find a matching report, check it carefully: + + * If it is less than a month old and without a single doubt about the sa= me + issue, consider replying to tell involved people that you are affected= as + well. + + * If it just looks quite a lot like the same issue, send a reply briefly + describing your problem and ask if it might be the same issue; if you = do + receive a negative reply or none at all, report the problem anew separ= ately. + + * In all other cases, prepare a separate report by following this guide + further and linking to any possibly related reports in yours. + + When you find fixes, consider trying them. If they work and are not yet + committed, write a short reply to let the developers know. If they don't = work + while fixing the issue for other people, you most likely face a different + problem you have to report independently while linking to the earlier rep= ort. + + [:ref:`details `] =20 - * Perform a rough search for existing reports with your favorite internet - search engine; additionally, check the archives of the `Linux Kernel Ma= iling - List (LKML) `_. If you find matching rep= orts, - join the discussion instead of sending a new one. =20 * See if the issue you are dealing with qualifies as regression, security issue, or a really severe problem: those are 'issues of high priority' = that @@ -534,53 +554,97 @@ out a few common causes before wasting time on a mean= ingless bug report: [:ref:`back to step-by-step guide `] =20 =20 -Search for existing reports, first run --------------------------------------- - - *Perform a rough search for existing reports with your favorite internet - search engine; additionally, check the archives of the Linux Kernel Mai= ling - List (LKML). If you find matching reports, join the discussion instead = of - sending a new one.* - -Reporting an issue that someone else already brought forward is often a wa= ste of -time for everyone involved, especially you as the reporter. So it's in you= r own -interest to thoroughly check if somebody reported the issue already. At th= is -step of the process it's okay to just perform a rough search: a later step= will -tell you to perform a more detailed search once you know where your issue = needs -to be reported to. Nevertheless, do not hurry with this step of the report= ing -process, it can save you time and trouble. - -Simply search the internet with your favorite search engine first. Afterwa= rds, -search the `Linux Kernel Mailing List (LKML) archives -`_. - -If you get flooded with results consider telling your search engine to lim= it -search timeframe to the past month or year. And wherever you search, make = sure -to use good search terms; vary them a few times, too. While doing so try to -look at the issue from the perspective of someone else: that will help you= to -come up with other words to use as search terms. Also make sure not to use= too -many search terms at once. Remember to search with and without information= like -the name of the kernel driver or the name of the affected hardware compone= nt. -But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') -often is not much helpful, as it is too specific. Instead try search terms= like -the model line (Radeon 5700 or Radeon 5000) and the code name of the main = chip -('Navi' or 'Navi10') with and without its manufacturer ('AMD'). - -In case you find an existing report about your issue, join the discussion,= as -you might be able to provide valuable additional information. That can be -important even when a fix is prepared or in its final stages already, as -developers might look for people that can provide additional information or -test a proposed fix. Jump to the section 'Duties after the report went out= ' for -details on how to get properly involved. - -Note, searching `bugzilla.kernel.org `_ migh= t also -be a good idea, as that might provide valuable insights or turn up matching -reports. If you find the latter, just keep in mind: most subsystems expect -reports in different places, as described below in the section "Check wher= e you -need to report your issue". The developers that should take care of the is= sue -thus might not even be aware of the bugzilla ticket. Hence, check the tick= et if -the issue already got reported as outlined in this document and if not con= sider -doing so. +.. _checkloreone_repiref: + +Search for existing reports and fixes +------------------------------------- + + *Search lore.kernel.org for similar reports and potential fixes; afterwa= rds + the wider internet, too.* [:ref:`... `] + +You don't want to waste your time reporting an issue anew someone already +brought forward or resolved already. So it is in your own interest to chec= k for +existing reports and fixes. + +Searching for fixes and existing reports +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your search on `lore `_ and the web resul= ts in +a flood of results, consider limiting the search timeframe. In lore you ca= n do +so by adding something like 'rt:3.months.ago..' or 'rt:1.years.ago..' to y= our +query. + +Wherever you search, make sure to use good terms; vary them a few times, t= oo. + +Start with something specific and become broader if there are no or too few +results. Also try to look at the issue from the perspective of someone els= e: +that might help you to come up with other terms to use in your search. + +Remember to search with and without information like the name of the kernel +driver or the name of the affected hardware component. But its exact brand= name +(say, 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') often is way too speci= fic; +instead, try search terms like the model line ('Radeon 5700' or 'Radeon 50= 00') +and the code name of the main chip ('Navi' or 'Navi10') with and without t= he +manufacturer of the main chip's name ('AMD') or the product's series +('Radeon'). + +Try fixes and evaluate matching reports closely +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you find a potential fix, give it a try; if it is still under discussio= n and +helps, let the developers know through a short reply. + +You found matching reports or a fix that does not help? Then evaluate them +closely, as they might be about a different issue with similar symptoms. Y= our +next steps depend on the outcome: + +* Is the report or fix still discussed and without any doubt about an issu= e like + yours? Then join the exchange, as you might be able to provide valuable + additional information or test results. + +* If the report or fix seems to be about a different issue, ignore it and + proceed with this guide, but briefly mention and link the earlier report= or + fix in your report later. After reporting, it might also be wise to send= a + short reply to the earlier report with a text along the lines of 'To who= m it + may concern, I ran into a similar, but from my understanding slightly + different problem', coupled with a link to the report. + +* When unsure if it is the same or a different problem, send a short reply= to + the earlier report or fix; in it, very briefly outline the problem while + asking if that seems to be the same problem or a different one better + reported separately. + +While doing so, keep in mind: + +* Chaos and confusion easily ensue when an issue is reported in a bug trac= ker + ticket or mailing list thread that looks related, but, in fact, is about= a + different issue. Try hard to avoid such an outcome, as then it can quick= ly + happen that none of the problems will be addressed in the end. The best + strategy to avoid that: Whenever there is a slight chance that your issue + might be different, report it in a new ticket or thread, but mention the + earlier reports you found; afterwards send a short reply to the earlier + ticket/thread with a text along the lines of 'I have a similar problem w= hich + might or might not be related' coupled with a link to your report. + +* Never report an issue in a bug tracker ticket or a mailing list thread t= hat + looks related, but is considered resolved. Always report in a new thread + instead; afterwards send a short reply to the earlier ticket/thread with= a + text along the lines of 'I have a similar problem which might or might n= ot be + related' coupled with a link to your report. + +* When spotting matching reports on `bugzilla.kernel.org + `_, keep in mind that the appropriate + developers to handle the issue might not even be aware of the report. Th= at is + because Bugzilla might not have forwarded the report to them: It lacks t= he + necessary information to do so for many of the kernel's subsystems, as t= heir + developers expect reports in different places -- ':ref:`Check how to rep= ort + your issue `' describes this in more detail. If in + doubt, add a comment to the Bugzilla report; if no reassuring answer is + forthcoming, report the issue briefly through the proper channel while + mentioning the Bugzilla report; afterwards add a comment to the latter + pointing to your report. + +[:ref:`back to step-by-step guide `] =20 =20 Issue of high priority? --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 BEFB92DEA86; Sun, 26 Oct 2025 12:42:35 +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=1761482559; cv=none; b=DWxTXNujdsjxi96p9xWVhNhnEEvC8IDj74hNn/9zaw7uXcVlZacwdRxe7vvvEtd2TnZ88iOXGUjhiY934ttPkcQjko29TNk/V7/RwieWzg4USpHtZC3i/5L9ZK4l/AIEO1V1S7bJYsO5IE2FO3E+HA4zztE+uDaTZpT5q5ihuRw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482559; c=relaxed/simple; bh=ssVvwoFpHksR7S1yAW0o5ytD10Wjf8FwhSwY9WdtQzQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=B6GL6pcOCWD0e143aFflW01/jX388paXR8YOnJ7j46lX1hzyxuCxdYdggUY5W7vHgwSafmrxE84GE3jmudgJ3ioYVtoZNuNrvsTsjfDMxqIqHi3YkCiKsv1zuHjq1O8X0+8EWmWn12bc38Z8WtP8tMZFxwANyEJZVRBa0J/P8wM= 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=R33DzFEb; 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="R33DzFEb" 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=wxOJZPwa+y+t+XC7Eo7yNZo1Tn0YNyHGnurlluB3qas=; t=1761482555; x=1761914555; b=R33DzFEbexS6mTtXMBUiY3W7sQ/aHOMkt33oO6eErJCr/Np9WCaoU/dnwyjAN 7VHmiXiI8/aUfyvw5xNyxL3RI/nUqjgnsdS3lpEMLKJpSy34WUaH6bvGUo/UVlfBej8wRUM3ZmH4Y cBFc3s16UKLSUEpH7V4y96kYuxu1I8LM+SmlmRd7M1DHuQarbhnvS8GKMok8iogAhGXPazmDscmlO tRCjmfq9kyX98J/vpv0VCMIw+hHaYNSz3puCS5+SYgandK/b2KrzpQVkitF9G6F6cUJUmLwNqv2fr PcTPQZSC2HnkG8hiFWF2yoqqcbDihty5xBd+Jzg9s4f+OEg+OA==; 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-0F; Sun, 26 Oct 2025 13:42:28 +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 15/30] docs: reporting-issues: improve text on classifying the bug Date: Sun, 26 Oct 2025 13:42:06 +0100 Message-ID: <72dc704c18af85ea8b5a80b9c3714588235d0797.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;1761482555;32bd3f7a; X-HE-SMSGID: 1vD04q-001mYF-0F Content-Type: text/plain; charset="utf-8" Fine-tune the instructions about classifying the bug. This drops support for "really severe problems", this is a rare special case not woth spending much thought on. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 62 +++++++++---------- 1 file changed, 29 insertions(+), 33 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 623feb55caae97..be0e49046ec913 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -128,10 +128,13 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 +.. _specialtreat_repisbs: =20 - * See if the issue you are dealing with qualifies as regression, security - issue, or a really severe problem: those are 'issues of high priority' = that - need special handling in some steps that are about to follow. +* Evaluate if the issue you are dealing with qualifies as a regression or + security issue, as those receive special treatment in some of the follow= ing + steps. + + [:ref:`details `] =20 * Create a fresh backup and put system repair and restore tools at hand. =20 @@ -647,37 +650,30 @@ While doing so, keep in mind: [:ref:`back to step-by-step guide `] =20 =20 -Issue of high priority? ------------------------ +.. _specialtreat_repiref: + +Issues receiving special treatment +---------------------------------- + + *Evaluate if the issue you are dealing with qualifies as a regression or + security issue, as those* [:ref:`... `] + +Check if you face an issue that receives special treatment in the Linux +development process: + +* You deal with a regression, if some application or practical use case ru= nning + fine with one Linux kernel version works worse or not at all with a newer + version compiled using a similar configuration; the 'no regression' rule + forbids that. The document + Documentation/admin-guide/reporting-regressions.rst explains these and + additional aspects in more detail, but everything important is covered in + this document. + +* What qualifies as a security issue is left to your judgment. Consider re= ading + Documentation/process/security-bugs.rst before proceeding, which + provides instructions on handling security issues. =20 - *See if the issue you are dealing with qualifies as regression, securi= ty - issue, or a really severe problem: those are 'issues of high priority'= that - need special handling in some steps that are about to follow.* - -Linus Torvalds and the leading Linux kernel developers want to see some is= sues -fixed as soon as possible, hence there are 'issues of high priority' that = get -handled slightly differently in the reporting process. Three type of cases -qualify: regressions, security issues, and really severe problems. - -You deal with a regression if some application or practical use case runni= ng -fine with one Linux kernel works worse or not at all with a newer version -compiled using a similar configuration. The document -Documentation/admin-guide/reporting-regressions.rst explains this in more -detail. It also provides a good deal of other information about regression= s you -might want to be aware of; it for example explains how to add your issue t= o the -list of tracked regressions, to ensure it won't fall through the cracks. - -What qualifies as security issue is left to your judgment. Consider reading -Documentation/process/security-bugs.rst before proceeding, as it -provides additional details how to best handle security issues. - -An issue is a 'really severe problem' when something totally unacceptably = bad -happens. That's for example the case when a Linux kernel corrupts the data= it's -handling or damages hardware it's running on. You're also dealing with a s= evere -issue when the kernel suddenly stops working with an error message ('kernel -panic') or without any farewell note at all. Note: do not confuse a 'panic= ' (a -fatal error where the kernel stop itself) with a 'Oops' (a recoverable err= or), -as the kernel remains running after the latter. +[:ref:`back to step-by-step guide `] =20 =20 Prepare for emergencies --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 29D4C2DE6F2; Sun, 26 Oct 2025 12:42:35 +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=1761482557; cv=none; b=QkkiA2AgK1A3mnbX3K/OXUSOZmvjjY2hUJaPGPTfC02ZyrfqqWIMQ8lBDXZsBwIJkhNTpUeEW+vCwyDT8RaiK0YQTphUTLCXnVgFoUYaQhfibLbUNP+r4LIv78jSGsasrmbetHVrZeYgWgEG68DL9/XhAV4T3jl+ePiGvmDqYno= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482557; c=relaxed/simple; bh=Ofxx0+c/MRp/TNjJRRAi4gsRd25jUdBrB86emjyGm/E=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Y/nzZ5YZTHRKY0IreimWTZLvLs119bVL+1dqykyM0OrjnVS8Bp/lJoj5gWlLIH67bHKyYs9cE8llmcYMlJJyGkNSskDiTg2fwzWqhA0bQuHpi+8+9c5TtxSVQm0L/HR8Pjm/jSNhpsLgEFUD67i92gQ8UWGx7aJXn7VGRWzVnKo= 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=oolSZuUY; 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="oolSZuUY" 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=3CHjp0Wli2N5/16/s/0lV/OPy7U+/3+rC+O47XOU8ng=; t=1761482555; x=1761914555; b=oolSZuUYx/fb4n8g2yP3th0cdGvq2ttkahzQizFIx32u+Miuu3lAXoFL7+dzH nDsjdxtLBpqGkSWKVGs5lhrKcZIXtGn8zfxzlLUgRhatueUmDh/fWuFHwwojxW9giMq06gTqF2j+5 F6cJBx1uLPy3nO97gUlzhcvdlelSVRt5pk/OXv2rPhwjJI3g6EkKmEroVOp5zKBBmrMd+kcgtYSnA /aOteDEH89f+T9bf26d1eHppR/gRKho9ojgMf6wRSMNSTKMa9bWfDRSSi1VMDeqSjAoeOaeAe4WoC sCkTfwCQ2Qdlo7qoJPYebPDeNtTqxNd0e6CW934AxOjyiOzCzQ==; 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-1K; Sun, 26 Oct 2025 13:42:28 +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 16/30] docs: reporting-issues: add fast-track for regressions Date: Sun, 26 Oct 2025 13:42:07 +0100 Message-ID: <279303a7d230ac7c9db13cf7cf807732946badb3.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;1761482555;32bd3f7a; X-HE-SMSGID: 1vD04q-001mYF-1K Content-Type: text/plain; charset="utf-8" Some regressions are reported multiple times within a short time frame, so it's worth asking on the regressions mailing list: subscribers might already known about them and might safe the reporter a lot of trouble, as reporting it again is unlikely to do much of a difference. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index be0e49046ec913..f040ca7c0a2f59 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -136,6 +136,19 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 +.. _reginquiry_repisbs: + +* Do you face a regression? One still occurring in a kernel version less t= han + two (ideally: one) weeks old? A kernel that is vanilla or close to it? If + you answered all three questions with 'yes', feel free to send a brief e= mail + to the public 'Linux regressions mailing list ' + asking if the problem is known. If someone confirms this to be the case, + there most likely is no need to follow this guide further; but do so in = case + there is no reply with a pointer to a matching report within two or three + weekdays. You are also free to immediately continue if you feel like it. + + [:ref:`details `] + * Create a fresh backup and put system repair and restore tools at hand. =20 * Ensure your system does not enhance its kernels by building additional @@ -676,6 +689,22 @@ development process: [:ref:`back to step-by-step guide `] =20 =20 +.. _reginquiry_repiref: + +Fast track for regressions +-------------------------- + + *Do you face a regression? One still occurring in a kernel version less = than + two (ideally: one) weeks old? A kernel that is vanilla or close to it? I= f you + answered* [:ref:`... `] + +This is an optional fast track that might relieve you from further work on +reporting in case the issue is already known. Note: It are volunteers that +answer these emails on a best-effort basis. + +[:ref:`back to step-by-step guide `] + + Prepare for emergencies ----------------------- =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 69B182C0289; 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=1761482552; cv=none; b=XI/yjRO5yJoTq5fmaPpBhIt92MwH6sl0gvTsgUoQ2glaa/gtdczhAcQ7iR03lX4MwbxbYMQrz3SMmBfxM0I6sbekIP0KCJ6rlXBh3XJErJjkeK45p/kSxD7sZdYpae39G5m9+Dp1bpITaP260lAgZvklZafgfBhLDuwu9k/1peQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482552; c=relaxed/simple; bh=pigXJFEk84kaIiULbwp7KdKvqomNcO+IDSl4650sWc8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=e4lqi8GSHGuCglzQ4s6ylJsBwwb6ykQpelA28yOze475B6A/YbxyApxY+bjdQAMWkorMxKQ2uxP+Mu35s1y0qpCb3EuVRqTCQ7jj0sV3e8E3T+LIbEEmHeZWwu3CWYf4gub7vWTGmH5Y1l+dnJMqm5n+Rm+7wruP43+ICCtXcFk= 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=djlp42xb; 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="djlp42xb" 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=2YS+YgaQrR4MfKIsndWYMCSVGSnj2HS6wx9rm7xWb7Q=; t=1761482550; x=1761914550; b=djlp42xbwhGjtrFG6Jfe3jkrZLd1wb1pCa6ZpwJVjWDqzdl2fthKONBDR1nI1 BKs+UBsylD9nu9Feya+WmNogVciBmbNd44bZND1vgBiw+u9cO9bDMBAxYyq7Tzcy4EbMKOO1j0fpU wQqTiSm+GwQ2hAyy8Cd7h37IO1JKwOOoyfGuL8vECo2EjHGogDAk41hGlK8OcxsVWADFz3P5HQ8Z9 xtoeEMAHsp+8qy+aJ5YoWWDM13FK3u90OuHFH8B7pryfCyEMERgBSegDc4TB+wiD5xxSMGjgpkb9J xVg9yDYYKGFs9N/uDdMBMxB/f2wiGMSod38I2Hdt6KzQ5AIGEA==; 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-2G; Sun, 26 Oct 2025 13:42:28 +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 17/30] docs: reporting-issues: move text on 'check MAINTAINERS file' upwards Date: Sun, 26 Oct 2025 13:42:08 +0100 Message-ID: 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-2G Content-Type: text/plain; charset="utf-8" Move text around to improve diffability of a follow-up patch. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 162 +++++++++--------- 1 file changed, 81 insertions(+), 81 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index f040ca7c0a2f59..e9d304040e3b54 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -149,6 +149,11 @@ 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. + * Create a fresh backup and put system repair and restore tools at hand. =20 * Ensure your system does not enhance its kernels by building additional @@ -161,11 +166,6 @@ following the others is usually in your own interest. (say something broke when updating from 5.10.4 to 5.10.5), scroll down = to 'Dealing with regressions within a stable and longterm kernel line'. =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. - * Search the archives of the bug tracker or mailing list in question thoroughly for reports that might match your issue. If you find anythin= g, join the discussion instead of sending a new report. @@ -705,73 +705,6 @@ answer these emails on a best-effort basis. [:ref:`back to step-by-step guide `] =20 =20 -Prepare for emergencies ------------------------ - - *Create a fresh backup and put system repair and restore tools at hand= .* - -Reminder, you are dealing with computers, which sometimes do unexpected th= ings, -especially if you fiddle with crucial parts like the kernel of its operati= ng -system. That's what you are about to do in this process. Thus, make sure to -create a fresh backup; also ensure you have all tools at hand to repair or -reinstall the operating system as well as everything you need to restore t= he -backup. - - -Make sure your kernel doesn't get enhanced ------------------------------------------- - - *Ensure your system does not enhance its kernels by building additional - kernel modules on-the-fly, which solutions like DKMS might be doing lo= cally - without your knowledge.* - -The risk your issue report gets ignored or rejected dramatically increases= if -your kernel gets enhanced in any way. That's why you should remove or disa= ble -mechanisms like akmods and DKMS: those build add-on kernel modules -automatically, for example when you install a new Linux kernel or boot it = for -the first time. Also remove any modules they might have installed. Then re= boot -before proceeding. - -Note, you might not be aware that your system is using one of these soluti= ons: -they often get set up silently when you install Nvidia's proprietary graph= ics -driver, VirtualBox, or other software that requires a some support from a -module not part of the Linux kernel. That why your might need to uninstall= the -packages with such software to get rid of any 3rd party kernel module. - - -Document how to reproduce issue -------------------------------- - - *Write down coarsely how to reproduce the issue.* - -During the reporting process you will have to test if the issue -happens with other kernel versions. Therefore, it will make your work easi= er if -you know exactly how to reproduce an issue quickly on a freshly booted sys= tem. - -Note: it's often fruitless to report issues that only happened once, as th= ey -might be caused by a bit flip due to cosmic radiation. That's why you shou= ld -try to rule that out by reproducing the issue before going further. Feel f= ree -to ignore this advice if you are experienced enough to tell a one-time err= or -due to faulty hardware apart from a kernel issue that rarely happens and t= hus -is hard to reproduce. - - -Regression in stable or longterm kernel? ----------------------------------------- - - *If you are facing a regression within a stable or longterm version li= ne - (say something broke when updating from 5.10.4 to 5.10.5), scroll down= to - 'Dealing with regressions within a stable and longterm kernel line'.* - -Regression within a stable and longterm kernel version line are something = the -Linux developers want to fix badly, as such issues are even more unwanted = than -regression in the main development branch, as they can quickly affect a lo= t of -people. The developers thus want to learn about such issues as quickly as -possible, hence there is a streamlined process to report them. Note, -regressions with newer kernel version line (say something broke when switc= hing -from 5.9.15 to 5.10.5) do not qualify. - - Check where you need to report your issue ----------------------------------------- =20 @@ -886,18 +819,18 @@ to find all people to contact. It queries the MAINTAI= NERS file and needs to 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:: =20 - $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kerne= l/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!' - drivers/net/wireless/ath/ath10k/ath10k_pci.ko + $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!= ; s!filename:!!; s!\.ko\(\|\.xz\)!!' + drivers/net/wireless/ath/ath10k/ath10k_pci.ko =20 Pass parts of this to the script:: =20 - $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k* - Some Human (supporter:QUALCOMM ATHEROS ATH10K = WIRELESS DRIVER) - Another S. Human (maintainer:NETWORKING DR= IVERS) - ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIREL= ESS DRIVER) - linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIREL= ESS)) - netdev@vger.kernel.org (open list:NETWORKING DRIVERS) - linux-kernel@vger.kernel.org (open list) + $ ./scripts/get_maintainer.pl --no-git -f drivers/net/wireless/ath/ath1= 0k* + Some Human (supporter:QUALCOMM ATHEROS ATH10K WIRE= LESS DRIVER) + Another S. Human (maintainer:NETWORKING DRIVER= S) + ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS = DRIVER) + linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS)) + 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 @@ -915,6 +848,73 @@ modified during tree-wide cleanups by developers that = do not care about the particular driver at all. =20 =20 +Prepare for emergencies +----------------------- + + *Create a fresh backup and put system repair and restore tools at hand= .* + +Reminder, you are dealing with computers, which sometimes do unexpected th= ings, +especially if you fiddle with crucial parts like the kernel of its operati= ng +system. That's what you are about to do in this process. Thus, make sure to +create a fresh backup; also ensure you have all tools at hand to repair or +reinstall the operating system as well as everything you need to restore t= he +backup. + + +Make sure your kernel doesn't get enhanced +------------------------------------------ + + *Ensure your system does not enhance its kernels by building additional + kernel modules on-the-fly, which solutions like DKMS might be doing lo= cally + without your knowledge.* + +The risk your issue report gets ignored or rejected dramatically increases= if +your kernel gets enhanced in any way. That's why you should remove or disa= ble +mechanisms like akmods and DKMS: those build add-on kernel modules +automatically, for example when you install a new Linux kernel or boot it = for +the first time. Also remove any modules they might have installed. Then re= boot +before proceeding. + +Note, you might not be aware that your system is using one of these soluti= ons: +they often get set up silently when you install Nvidia's proprietary graph= ics +driver, VirtualBox, or other software that requires a some support from a +module not part of the Linux kernel. That why your might need to uninstall= the +packages with such software to get rid of any 3rd party kernel module. + + +Document how to reproduce issue +------------------------------- + + *Write down coarsely how to reproduce the issue.* + +During the reporting process you will have to test if the issue +happens with other kernel versions. Therefore, it will make your work easi= er if +you know exactly how to reproduce an issue quickly on a freshly booted sys= tem. + +Note: it's often fruitless to report issues that only happened once, as th= ey +might be caused by a bit flip due to cosmic radiation. That's why you shou= ld +try to rule that out by reproducing the issue before going further. Feel f= ree +to ignore this advice if you are experienced enough to tell a one-time err= or +due to faulty hardware apart from a kernel issue that rarely happens and t= hus +is hard to reproduce. + + +Regression in stable or longterm kernel? +---------------------------------------- + + *If you are facing a regression within a stable or longterm version li= ne + (say something broke when updating from 5.10.4 to 5.10.5), scroll down= to + 'Dealing with regressions within a stable and longterm kernel line'.* + +Regression within a stable and longterm kernel version line are something = the +Linux developers want to fix badly, as such issues are even more unwanted = than +regression in the main development branch, as they can quickly affect a lo= t of +people. The developers thus want to learn about such issues as quickly as +possible, hence there is a streamlined process to report them. Note, +regressions with newer kernel version line (say something broke when switc= hing +from 5.9.15 to 5.10.5) do not qualify. + + Search for existing reports, second run --------------------------------------- =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 From nobody Sun Feb 8 13:08:52 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 0979D2D7DF1; 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=b390zb8++lncefXHZ0IrpP04jiUg9EJwn4XI0DOR94lFslUqMZRN34tzCtzv0DeeKzxNp1BRbox8FoeGzfhcH42c7wjtbdprU0dixIuvbTYY8DgCFzaComLaXJ80BFzb7t4oT8hLAKcKsNZGF7teLsM7Znvt8JFqRcVUbh83lu4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482553; c=relaxed/simple; bh=zdHVVuWMdLD/IA0oLUCz2dfrOnOXQo2D2OWsrWMT4AI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=FNByPIqNKBIBHEa6x3guZRE2LvSTmgBZYwWVgjkYPP4GKNTuopWXaWbqq0P53jU5sR8ojP4Br1lBsloALE5Ld0JMZy3ibwlYu+iX9GVGAek8BcUS2ul1TXqXGL9VTwib/PiC4AlPGQr4A/Zf4UwzoScUxXUH7sX4F6LVPdT2Ttc= 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=1q8fE0lt; 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="1q8fE0lt" 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=fHLnuG6RM3Qg3mrCT9HfBteDN/mL5635GCoRcQ8os+0=; t=1761482551; x=1761914551; b=1q8fE0ltuE1TrfIzW9wIfGzR3W6ADY1DQUrFTyNNy34vcBbfNZMEIOOoCwW2A qxZVtHXmnFOpPmj9V0FysKwu1sEYgyDD1Smy+v9UNis89z0Hy/bHy7tTPcK4FtHKN0MHy+6pyh4jD SN8Sz3m7HJDP+KojWsxdxDtxFBFqQd/S0IvXTsoYCVcgc4SKExVLXIITx0ziWQlAxHw1fQ0sWcTbj t8lXLyFUchQ8OlNMsdP7jG4Roj/ixrFg+uOF9izFDqwVQGgq2orPxBf+wJ5rMCvREWnXJ9HcDYUkM xG9TyNkSLoKm0HYTQTU9Ts+B5UNisZETsEdWBq4eW+WLNgINaQ==; 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 1vD04r-001mYF-0z; 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 19/30] docs: reporting-issues: move text on 'check other places' upwards Date: Sun, 26 Oct 2025 13:42:10 +0100 Message-ID: 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;1761482551;009d26c6; X-HE-SMSGID: 1vD04r-001mYF-0z Content-Type: text/plain; charset="utf-8" Move text around to improve diffability of a follow-up patch. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 82 +++++++++---------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 56e004ba038403..baee1da327d116 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -157,6 +157,10 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 + * Search the archives of the bug tracker or mailing list in question + thoroughly for reports that might match your issue. If you find anythin= g, + join the discussion instead of sending a new report. + * Create a fresh backup and put system repair and restore tools at hand. =20 * Ensure your system does not enhance its kernels by building additional @@ -169,10 +173,6 @@ following the others is usually in your own interest. (say something broke when updating from 5.10.4 to 5.10.5), scroll down = to 'Dealing with regressions within a stable and longterm kernel line'. =20 - * Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. If you find anythin= g, - join the discussion instead of sending a new report. - After these preparations you'll now enter the main part: =20 * Unless you are already running the latest 'mainline' Linux kernel, bett= er @@ -851,6 +851,43 @@ about the particular driver at all. [:ref:`back to step-by-step guide `] =20 =20 +Search for existing reports, second run +--------------------------------------- + + *Search the archives of the bug tracker or mailing list in question + thoroughly for reports that might match your issue. If you find anythi= ng, + join the discussion instead of sending a new report.* + +As mentioned earlier already: reporting an issue that someone else already +brought forward is often a waste of time for everyone involved, especially= you +as the reporter. That's why you should search for existing report again, n= ow +that you know where they need to be reported to. If it's mailing list, you= will +often find its archives on `lore.kernel.org `_. + +But some list are hosted in different places. That for example is the case= for +the ath10k WiFi driver used as example in the previous step. But you'll of= ten +find the archives for these lists easily on the net. Searching for 'archive +ath10k@lists.infradead.org' for example will lead you to the `Info page fo= r the +ath10k mailing list `= _, +which at the top links to its +`list archives `_. Sadly th= is and +quite a few other lists miss a way to search the archives. In those cases = use a +regular internet search engine and add something like +'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which l= imits +the results to the archives at that URL. + +It's also wise to check the internet, LKML and maybe bugzilla.kernel.org a= gain +at this point. If your report needs to be filed in a bug tracker, you may = want +to check the mailing list archives for the subsystem as well, as someone m= ight +have reported it only there. + +For details how to search and what to do if you find matching reports see +"Search for existing reports, first run" above. + +Do not hurry with this step of the reporting process: spending 30 to 60 mi= nutes +or even more time can save you and others quite a lot of time and trouble. + + Prepare for emergencies ----------------------- =20 @@ -918,43 +955,6 @@ regressions with newer kernel version line (say someth= ing broke when switching from 5.9.15 to 5.10.5) do not qualify. =20 =20 -Search for existing reports, second run ---------------------------------------- - - *Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. If you find anythi= ng, - join the discussion instead of sending a new report.* - -As mentioned earlier already: reporting an issue that someone else already -brought forward is often a waste of time for everyone involved, especially= you -as the reporter. That's why you should search for existing report again, n= ow -that you know where they need to be reported to. If it's mailing list, you= will -often find its archives on `lore.kernel.org `_. - -But some list are hosted in different places. That for example is the case= for -the ath10k WiFi driver used as example in the previous step. But you'll of= ten -find the archives for these lists easily on the net. Searching for 'archive -ath10k@lists.infradead.org' for example will lead you to the `Info page fo= r the -ath10k mailing list `= _, -which at the top links to its -`list archives `_. Sadly th= is and -quite a few other lists miss a way to search the archives. In those cases = use a -regular internet search engine and add something like -'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which l= imits -the results to the archives at that URL. - -It's also wise to check the internet, LKML and maybe bugzilla.kernel.org a= gain -at this point. If your report needs to be filed in a bug tracker, you may = want -to check the mailing list archives for the subsystem as well, as someone m= ight -have reported it only there. - -For details how to search and what to do if you find matching reports see -"Search for existing reports, first run" above. - -Do not hurry with this step of the reporting process: spending 30 to 60 mi= nutes -or even more time can save you and others quite a lot of time and trouble. - - Install a fresh kernel for testing ---------------------------------- =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 820392D7DFF; Sun, 26 Oct 2025 12:42:31 +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=UpY2YN11yVaBilMjdCMiZtPtxvynybXVmgm77AAmGjGq6KNaDsEkkGPjN2NJz//OQeTW7xVbge3dyMoXDK39zIDf9QhvbELwGSO7qN3ZCfUw7qHeoYCWrJJHYFM6ccncJz7x5ajMeoP4HvSE+sYiyLhfOkQPPQmu7PpArDTTiag= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482553; c=relaxed/simple; bh=Jhphcb2eOJvYE4YvsIZauiMAEtvFpkvShA2BIkzuVJE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=UAs9nIWVLc5Khsi0UNxNpyIgSBc+tvjhSdv2OPxhX1f4XRdnCYrI0/a62JPwq+qya8SLAM6aO65OChtmQV51X8J++7I3Dw2nqWtTVfll64/ORZmXAs4duqQMMFkkvWWrLGlrKSLHy8eOJfiHS27o4LJFvRB5agqEDLj9RSooYJE= 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=kg8udvqb; 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="kg8udvqb" 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=lPjt0MqJvH6hs507jG7OGwNx1ZlrR2+68vhiSR2b17I=; t=1761482551; x=1761914551; b=kg8udvqb6gkbHUAi0XOrwvWSuBokh3Ml3IDuq0j5XXWfr0XoaKgEBImZAPjfY NgtSndcxjbS4zLOAyybriYX2qnG9zwSThnubIwgsOBF2Im0tx3CUdCgWL9wON1fdfZyCi9HSl/HPt N3MDouQCIUo5utVRZt30lR+LBRRQI8L8FYQPY0Lnxa3JCR7kpRabUMJjdTXKLsY6nrwER2/+Ek4Pv T//9jNaofNA01o5oYcRMhuNZ6xbi35j2l+leJ7Oglyol3IqOBis3YF0kBfMVdzbCoXkN9nfM0DUbI fhakJaeG5SqLJZHYIkjveeEWF/2BdGY4nNus7hmMWrA+mj9+Sg==; 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 1vD04r-001mYe-2u; 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 20/30] docs: reporting-issues: improve text on check other places Date: Sun, 26 Oct 2025 13:42:11 +0100 Message-ID: <1a654e35cf72a349b5882b010ac9ad5f34830f9a.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;1761482551;009d26c6; X-HE-SMSGID: 1vD04r-001mYe-2u Content-Type: text/plain; charset="utf-8" Fine-tune the instructions about checking other places for existing reports. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 72 +++++++++++-------- 1 file changed, 44 insertions(+), 28 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index baee1da327d116..c34a95d5af4ac6 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -157,9 +157,24 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 - * Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. If you find anythin= g, - join the discussion instead of sending a new report. +.. _otherplaces_repisbs: + +* If the developers of the affected driver or subsystem use a dedicated ma= iling + list not `archived on lore `_, search its arch= ives + for earlier reports and potential fixes; if the subsystem is among the f= ew + using one of various bug trackers, search it as well. + + Checking `bugzilla.kernel.org `_ might be = worth + a shot, too. But keep in mind that for most of the kernel it is the wrong + place to submit bug reports: Many Linux developers do not care about the= bug + tracker and are not even notified about bugs in their code submitted the= re. + + If you find matching reports or fixes in either place, follow the instru= ctions + provided earlier. In the case of Bugzilla, check if the appropriate deve= lopers + noticed the ticket -- and if not, consider sending an email to the respo= nsible + people and lists pointing them to it. + + [:ref:`details `] =20 * Create a fresh backup and put system repair and restore tools at hand. =20 @@ -851,41 +866,42 @@ about the particular driver at all. [:ref:`back to step-by-step guide `] =20 =20 -Search for existing reports, second run ---------------------------------------- +.. _otherplaces_repiref: =20 - *Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. If you find anythi= ng, - join the discussion instead of sending a new report.* - -As mentioned earlier already: reporting an issue that someone else already -brought forward is often a waste of time for everyone involved, especially= you -as the reporter. That's why you should search for existing report again, n= ow -that you know where they need to be reported to. If it's mailing list, you= will -often find its archives on `lore.kernel.org `_. - -But some list are hosted in different places. That for example is the case= for -the ath10k WiFi driver used as example in the previous step. But you'll of= ten -find the archives for these lists easily on the net. Searching for 'archive -ath10k@lists.infradead.org' for example will lead you to the `Info page fo= r the -ath10k mailing list `= _, -which at the top links to its -`list archives `_. Sadly th= is and -quite a few other lists miss a way to search the archives. In those cases = use a -regular internet search engine and add something like +Search for existing reports in other places +------------------------------------------- + + *If the developers of the affected driver or subsystem use a dedicated + mailing list not archived on lore, search its archives for earlier repor= ts + and potential fixes; if the subsystem is* [:ref:`... `] + +Now that you know where they need to be reported to, search the target for +existing reports again. If it is a mailing list, you will often find its +archives on `lore `_. + +But some lists are hosted in different places. That, for example, is the c= ase +for the ath10k WiFi driver used as an example in the previous step. But yo= u'll +often find the archives for these lists easily on the net. Searching for +'archive ath10k@lists.infradead.org', for example, will lead you to the `I= nfo +page for the ath10k mailing list `_, +which at the top links to its `list archives `_. +Sadly, this and quite a few other lists miss a way to search the archives.= In +those cases, use a regular internet search engine and add something like 'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which l= imits the results to the archives at that URL. =20 -It's also wise to check the internet, LKML and maybe bugzilla.kernel.org a= gain +It is also wise to check the internet, LKML and maybe bugzilla.kernel.org = again at this point. If your report needs to be filed in a bug tracker, you may = want to check the mailing list archives for the subsystem as well, as someone m= ight have reported it only there. =20 -For details how to search and what to do if you find matching reports see -"Search for existing reports, first run" above. +For details on how to search and what to do if you find matching reports, = see +':ref:`Search for existing reports and fixes `' abov= e. =20 Do not hurry with this step of the reporting process: spending 30 to 60 mi= nutes -or even more time can save you and others quite a lot of time and trouble. +or even more time can save everyone, including you, quite some trouble. + +[:ref:`back to step-by-step guide `] =20 =20 Prepare for emergencies --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3DF5C2C235D; Sun, 26 Oct 2025 12:42:32 +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=1761482554; cv=none; b=Xj1WHKxJkaRu2zz5kCKRr8YvRpYrYw33Kw2GamiguBBY8J/y8aB+4tu84amfVr1mEnw8/kSIBuP5sqnOESVAaANdDj/d1lHxSQrgAwuOYQztIIEJ7z9CvxaNgxZsUtf+H+IGqEnCdAuuKDLsIGDWpY50t9RKseTAh5assFyvihc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482554; c=relaxed/simple; bh=EB4l20CtlH/TKvx8+1SQADxqp/5ETrJBw4utKo1I1YQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=daza3aThDYYSxRmARlcE56IXgizld1X9bJBRHr5qFGlrJHfbEtTIQmew8cR19KCjQsyHkx/7vr4rREZdVXvcG7qCqnPF2H8o/70bNddFPZ6rbeGzCJl2sdFjNuynpcg2GBSzL8zd4cISG6CTT+zWPv2VjoePOYfuvXKmcAr2Y0U= 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=aHE03fLk; 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="aHE03fLk" 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=n3DgjLvDifCmg81+qUxSYOLFkhBea1gNJNz0eht+0gI=; t=1761482552; x=1761914552; b=aHE03fLkagRB7iN0nzPP8FeKZdey/YnvOPft3W0ZKk8V7wb0VTRY0f672MLFs 8hlxiTf8w4quWxcuPGKsSWUxvP11ssoVXq6iLtrWQaHzLWGwTh0XHYnvBardY+cRb1kbTzcrsHL+4 me+U8O6L15Ph1FOUYxj7VURq2IaaxcR2co8Nyd//pOkqjw5/G5r60gqbSk38WyTNzF4eqoiC5hoZo SxgomC03tNdey+ENsTm8ZAZ85nNzXkW89bLvmKvCXaKOUWxNSa83wXZPgthSxo/c/y7u4ufcBNSXI amsxiOevS/uGhHaU225s30EFGERwaOKugM1CzMyRx/UUypcODA==; 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 1vD04s-001mYe-0l; Sun, 26 Oct 2025 13:42:30 +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 21/30] docs: reporting-issues: improve text on backup et. al Date: Sun, 26 Oct 2025 13:42:12 +0100 Message-ID: <13046cae22b876d818a8c49939bf5daac0437c5e.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;1761482552;81a32109; X-HE-SMSGID: 1vD04s-001mYe-0l Content-Type: text/plain; charset="utf-8" Fine-tune the instructions about creating a backup and preparing for emergencies. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 25 +++++++++++++------ 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index c34a95d5af4ac6..824b7b5394440e 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -176,7 +176,12 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 - * Create a fresh backup and put system repair and restore tools at hand. +.. _backup_repisbs: + +* You might want to create a fresh backup and put both system repair and + restore tools at hand. + + [:ref:`details `] =20 * Ensure your system does not enhance its kernels by building additional kernel modules on-the-fly, which solutions like DKMS might be doing loc= ally @@ -904,17 +909,21 @@ or even more time can save everyone, including you, q= uite some trouble. [:ref:`back to step-by-step guide `] =20 =20 +.. _backup_repiref: + Prepare for emergencies ----------------------- =20 - *Create a fresh backup and put system repair and restore tools at hand= .* + *You might want to create a fresh backup and put both* [:ref:`... `] + +Remember, you are dealing with computers, which sometimes do unexpected th= ings, +especially if you fiddle with crucial parts like their operating system ke= rnel. +That is what you are about to do in this process. You thus better want to = create +a fresh backup. In case you need to install a kernel during the bug report= ing +process, also ensure you have all tools at hand to repair or reinstall the +operating system as well as everything you need to restore the backup. =20 -Reminder, you are dealing with computers, which sometimes do unexpected th= ings, -especially if you fiddle with crucial parts like the kernel of its operati= ng -system. That's what you are about to do in this process. Thus, make sure to -create a fresh backup; also ensure you have all tools at hand to repair or -reinstall the operating system as well as everything you need to restore t= he -backup. +[:ref:`back to step-by-step guide `] =20 =20 Make sure your kernel doesn't get enhanced --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3E13D2DA775; Sun, 26 Oct 2025 12:42:32 +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=1761482554; cv=none; b=D0iMPGT4KM4Rd10mSJCBy/4n7we6ABT8pnPFU5KYoWdq0gTWwfhwmmPOa2arCTmLKT3eVb3wkR9MdO/X/uyWuWFjvEJSvRFk56VYaez54btuvu3Pn8LwzHeZzNPEVsKyTEhds705Y+TYdANZzp3vESomfZXGa7tvhULrR3M+ya0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482554; c=relaxed/simple; bh=aF4gOaHOL8y1v+VRh/H7S2DB1AvexVZI1NARJ9TVlxk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=XWp0Y2dR9B13+FI7yJK3+uJ3+KIiYilIv1li015zy/1ddwUcwutFHOQ68ItJkKO5vJR0OrqzFQgmo8jhi+YSUiQQE2TZWYdK/34K4/yMuS0S/yCoZCs1ZLhQ/JgLykKyqI04wKT8mNh2AIKWTxFhp+74Axa4F8OmYGAn9QwDh0A= 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=eSdU1W95; 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="eSdU1W95" 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=/qNrJQ0s2Mn0UJ5/hqRz3OJdxtP95JtfkjCzxkzcl7M=; t=1761482552; x=1761914552; b=eSdU1W95gc2qXtwDs/ZaUPx2Nl1Dx9k9JF7UHEfO1OQcVAxAuKA1PVRhkK63L SN5GvD8xGny+vY5JLZuYjKj6jcGpkT5GPrUfc2wo0Obj3FcohjhppcqgR0Xm1jQ0RBOYN/yNFIyv8 XFMn+fqwdgrxHge0M8Td+8sCUPX57lGcTNJ0utONAcCshU7IgoyTSaolh5VAT3lOd6xPZwYhsV9HP qprO6ChhJfBDhygxNa7j+B1YCtmyOxn7Dwde4azzTDAi4BqJFwsoHJ25qMDIFt169QkUlgCCh8aeY GmSyQ3HCQYuM3IkwsdKI43me9pQsEgXairR7N0/7Znb+s6zHOw==; 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 1vD04s-001mYe-1q; Sun, 26 Oct 2025 13:42:30 +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 22/30] docs: reporting-issues: move text on 'initial write-up' upwards Date: Sun, 26 Oct 2025 13:42:13 +0100 Message-ID: <769d2d492ac273f66a1e867bb17a14f32dde0d27.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;1761482552;81a32109; X-HE-SMSGID: 1vD04s-001mYe-1q Content-Type: text/plain; charset="utf-8" Move text around to improve diffability of a follow-up patch. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 39 +++++++++++-------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 824b7b5394440e..a5c40e75833638 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -183,10 +183,15 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 + * Write down coarsely how to reproduce the issue. + * Ensure your system does not enhance its kernels by building additional kernel modules on-the-fly, which solutions like DKMS might be doing loc= ally without your knowledge. =20 + * Check if your kernel was 'tainted' when the issue occurred, as the event + that made the kernel set this flag might be causing the issue you face. + * Write down coarsely how to reproduce the issue. =20 * If you are facing a regression within a stable or longterm version line @@ -926,6 +931,23 @@ operating system as well as everything you need to res= tore the backup. [:ref:`back to step-by-step guide `] =20 =20 +Document how to reproduce issue +------------------------------- + + *Write down coarsely how to reproduce the issue.* + +During the reporting process you will have to test if the issue +happens with other kernel versions. Therefore, it will make your work easi= er if +you know exactly how to reproduce an issue quickly on a freshly booted sys= tem. + +Note: it's often fruitless to report issues that only happened once, as th= ey +might be caused by a bit flip due to cosmic radiation. That's why you shou= ld +try to rule that out by reproducing the issue before going further. Feel f= ree +to ignore this advice if you are experienced enough to tell a one-time err= or +due to faulty hardware apart from a kernel issue that rarely happens and t= hus +is hard to reproduce. + + Make sure your kernel doesn't get enhanced ------------------------------------------ =20 @@ -947,23 +969,6 @@ module not part of the Linux kernel. That why your mig= ht need to uninstall the packages with such software to get rid of any 3rd party kernel module. =20 =20 -Document how to reproduce issue -------------------------------- - - *Write down coarsely how to reproduce the issue.* - -During the reporting process you will have to test if the issue -happens with other kernel versions. Therefore, it will make your work easi= er if -you know exactly how to reproduce an issue quickly on a freshly booted sys= tem. - -Note: it's often fruitless to report issues that only happened once, as th= ey -might be caused by a bit flip due to cosmic radiation. That's why you shou= ld -try to rule that out by reproducing the issue before going further. Feel f= ree -to ignore this advice if you are experienced enough to tell a one-time err= or -due to faulty hardware apart from a kernel issue that rarely happens and t= hus -is hard to reproduce. - - Regression in stable or longterm kernel? ---------------------------------------- =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 1FBE82DC34D; Sun, 26 Oct 2025 12:42:32 +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=1761482559; cv=none; b=twq/3WyzmzTJE6WWeS3iwJLj6ZxWbuXYH6e6Vx5Mpk9M/Jy1elAaNOUTB7fYWZQm9xfVyZztFMrPXh7W+ePv6Snyk2WYL3rvCMapxQ8dQ4HZ15c1SRWctcH2/CGOwW3I0Rs4oKH4iNTDfXTfMrZOEnBorCwl+7Wms+sfdnWOk6I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482559; c=relaxed/simple; bh=Ji8LR4L1NHfBVq73Eli0Sw59AUqjJ6VV3EUKjCfyvCs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=BFusvtT3/MzAzlBywnBSqAl70cDNvykFyAiVYal9mTaszspSy35c4Ff4rNeys39jOY9716hjrYuchxETsU8ZYowkCoOtHPeYsxaG7mpqo6u8keaV8IPPYwfWxzBuDp8jS38YwEVzgfg1Yx4vBgQ/e5pQNhGQwA0UEb3C7pF4XWQ= 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=GhKRiPti; 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="GhKRiPti" 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=05X04SjdCEaNS6JET3myuOA/oFj+Hu0euZBhdtro2oo=; t=1761482553; x=1761914553; b=GhKRiPtioRgb72mN6crmdHhjOBWp4djJJsgMJnHwkEdELf06MZRhKEsN18wUL QG0aM7da03lVU/4JebjRntM18o6YYOuhGos7fBh7CTKGhl8cBx60rpJzmYnvBx1L3QCJnTkhpAvZx JedzUanHgZvDhhkqlSu+12aKNB6fGcCtqRSbBRMwBIEUnqfPOYLhp4FQaH0BTv3GgWScGQs4hNQkp Yj986PSuAkoSbdXtoaTvW3C/EVESM+vGLSYBBEDAjFT08mcKn593BtZC+diHzEyH8c3Cj6IknJy+A /DL7LiBz7jQs6VbnA4Ji/O/saqSMbZzNcZCOBLZneXkBJVTp9g==; 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 1vD04s-001mYe-3A; Sun, 26 Oct 2025 13:42:31 +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 23/30] docs: reporting-issues: improve text on initial write-up Date: Sun, 26 Oct 2025 13:42:14 +0100 Message-ID: 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;1761482553;4a80bc7e; X-HE-SMSGID: 1vD04s-001mYe-3A Content-Type: text/plain; charset="utf-8" Fine-tune the instructions about coarsely writing down how to reproduce the problem. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 32 ++++++++++++------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index a5c40e75833638..f891764d4f64ce 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -183,7 +183,12 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 - * Write down coarsely how to reproduce the issue. +.. _coarsely_repisbs: + +* Write down coarsely how to reproduce the issue on a freshly booted syste= m in + a straightforward way you can easily reproduce. + + [:ref:`details `] =20 * Ensure your system does not enhance its kernels by building additional kernel modules on-the-fly, which solutions like DKMS might be doing loc= ally @@ -931,21 +936,26 @@ operating system as well as everything you need to re= store the backup. [:ref:`back to step-by-step guide `] =20 =20 -Document how to reproduce issue -------------------------------- +.. _coarsely_repiref: =20 - *Write down coarsely how to reproduce the issue.* +Start documenting how to reproduce issue +---------------------------------------- + + *Write down coarsely how to reproduce the issue on a freshly booted syst= em in* [:ref:`... `] =20 -During the reporting process you will have to test if the issue +During the reporting process, you most likely will have to test if the iss= ue happens with other kernel versions. Therefore, it will make your work easi= er if you know exactly how to reproduce an issue quickly on a freshly booted sys= tem. +And for the report you need a description anyway. + +This obviously is impossible in case you want to report an issue that happ= ened +just once. Be aware that it might be fruitless to report such problems, as +they might be caused by a bit flip due to cosmic radiation; but if you are +experienced enough to tell such a one-time hardware error apart from a ker= nel +issue that is worth reporting even without reproducing it, skip this step = and +the verification. =20 -Note: it's often fruitless to report issues that only happened once, as th= ey -might be caused by a bit flip due to cosmic radiation. That's why you shou= ld -try to rule that out by reproducing the issue before going further. Feel f= ree -to ignore this advice if you are experienced enough to tell a one-time err= or -due to faulty hardware apart from a kernel issue that rarely happens and t= hus -is hard to reproduce. +[:ref:`back to step-by-step guide `] =20 =20 Make sure your kernel doesn't get enhanced --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 3A8E32DC76C; Sun, 26 Oct 2025 12:42:33 +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=1761482558; cv=none; b=SowvyVS6qc/LJNyNbQQycMdnfbdcBL6McrfUdhs1GcMymV0N3Qi4WsOZYP4zZusMuzvzXEdhTisKIHz2elb97uTkTEI25ich50ETQaKX0lrBJ4qB455e9S6vFEtzfCmx9EEkrZ7Y1xmNq9RjpuC249j0ZW1yzo0RrgAgEKKGExo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482558; c=relaxed/simple; bh=pOqwtDHdRS58G7ZQ40ueHvkKEiOO/FXoywGUKaUsTkE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=FfyAl/vb/o1P4fgptI/hLryW5mHHCyotF/PIsn0N2SvvW+piY2udEIAPcQaykuwEch0fn3gN2u9JNh25iRH67ufYryNCZnithcydvnrbV3wqRGGpy7cRjWfIWe3naYyF6pB65sAxHdt3P6RpJrAhZg8acidyNdHQlpj/53b01rQ= 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=1KFZMedX; 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="1KFZMedX" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=leemhuis.info; s=he214686; h=Content-Transfer-Encoding:Content-Type: 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=ymzDNAJ8pWSBCtZPDPP82wHiAQGW1cXsJMWWKL0xjqs=; t=1761482553; x=1761914553; b=1KFZMedXWyAnls+A0wc9wULSHI/7NFFwpu4tvy91xQtPnw/rUPpxdzauiB/pN WpiDShzCctvKhc8ZgrDsVznnE1ps2cdcD2HRUOr46onHdRuNKqIpa1k2QKZqjD4IHqwCRksT8f/EQ 8M+n2cNAtlERQ+6lou1CfSOdLDBdpaLgWU6ACzo5WETtsEvmzQkWRWAeD870ZjwWhOuG3Ta+MJfW9 mVqFQZNYYiR05/1oTuu+tnwy8UIbkAs47Jc2R0SjKN1TEAMzJTQ23GITI6wDkZzlBjS65KkE0TjBo nXEnogtKX8FDsV213KXckVn+yPRpHofJF6u2gB5Hvn0XxRbHtQ==; 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 1vD04t-001mYe-19; Sun, 26 Oct 2025 13:42:31 +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 24/30] docs: reporting-issues: improve text on bug verification Date: Sun, 26 Oct 2025 13:42:15 +0100 Message-ID: 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-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1761482553;4a80bc7e; X-HE-SMSGID: 1vD04t-001mYe-19 Fine-tune the instructions about verifying the bug happens with a suitable kernel. This now heavily relies on Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst, which describes the necessary steps in a better and more straight-forward way. The new approach also makes things easier to follow for those that already run a suitable kernel. Regressions in stable/longterm are now covered by the regular steps to make things less confusing, as this was something people struggled with. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 560 ++++-------------- 1 file changed, 113 insertions(+), 447 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index f891764d4f64ce..9611514d10414e 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -190,36 +190,72 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 - * Ensure your system does not enhance its kernels by building additional - kernel modules on-the-fly, which solutions like DKMS might be doing loc= ally - without your knowledge. - - * Check if your kernel was 'tainted' when the issue occurred, as the event - that made the kernel set this flag might be causing the issue you face. - - * Write down coarsely how to reproduce the issue. - - * If you are facing a regression within a stable or longterm version line - (say something broke when updating from 5.10.4 to 5.10.5), scroll down = to - 'Dealing with regressions within a stable and longterm kernel line'. - -After these preparations you'll now enter the main part: - - * Unless you are already running the latest 'mainline' Linux kernel, bett= er - go and install it for the reporting process. Testing and reporting with - the latest 'stable' Linux can be an acceptable alternative in some - situations; during the merge window that actually might be even the best - approach, but in that development phase it can be an even better idea to - suspend your efforts for a few days anyway. Whatever version you choose, - ideally use a 'vanilla' build. Ignoring these advices will dramatically - increase the risk your report will be rejected or ignored. - - * Ensure the kernel you just installed does not 'taint' itself when - running. - - * Reproduce the issue with the kernel you just installed. If it doesn't s= how - up there, scroll down to the instructions for issues only happening with - stable and longterm kernels. +.. _verify_repisbs: + +* *You must* report the problem using a kernel suitable for reporting -- s= o you + have to verify it happens with such a kernel, unless you already run one= . In + case of a regression within a stable or longterm kernel, *you must* + furthermore check if the latest mainline kernel is affected as well. For + regressions in general, it is also recommended to locate the culprit usi= ng a + Git bisection. + + There are two approaches to realize those three requirements: + + * Follow 'Documentation/admin-guide/verify-bugs-and-bisect-regressions.r= st', + which is the recommended way. + + * Handle all tasks that document covers on your own: + + * For regressions within a stable or longterm series, check if the ser= ies is + still supported by ensuring `kernel.org `_ list= s it + without an 'EOL' tag. Then verify the problem still happens with the + latest release from that series; afterwards, check if the latest mai= nline + kernel is affected as well. When testing, ideally recheck with a van= illa + version of the working kernel and rule out a config change as the ro= ot of + your problem by building all newer Linux versions with a .config fro= m the + latest working kernel processed by ``make olddefconfig``. + + * In all other cases, check if the bug happens with a release, pre-rel= ease, + or snapshot of Linux mainline ideally less than one week old and two= at + maximum. The latest release from the newest stable series might work= out + as well, while longterm kernels rarely will. + + All kernels used for verifying additionally must meet the following + criteria: + + * The kernels should be 'vanilla', e.g., built from pristine Linux sou= rces + -- albeit reports from kernels built from lightly patched sources su= ch as + those used by default in Arch Linux, Debian GNU/Linux, Fedora Linux,= and + openSUSE Tumbleweed often work, too, as long as they are fresh enoug= h (see + above). The kernels of most other distributions are unsuitable; this + includes those Ubuntu and its derivatives use by default. + + * The kernels must remain 'vanilla' and thus never load any externally + developed modules, no matter if they are proprietary or Open Source.= This, + among others, means that you will have to steer clear of Nvidia's gr= aphics + drivers and OpenZFS as well as drivers VirtualBox or VMware Workstat= ion + install. + + * The kernels should not be 'tainted' before the issue occurs. If your= s is, + rule out that it has anything to do with the problem -- and if that = really + is the case, mention the reason for the tainting in your report late= r. + + Once you used either of the approaches to verify the problem with a suit= able + kernel, you are free to move on with this guide and report the problem. = Note, + though, in case it is regression not yet known, you most likely will be = asked + to perform a bisection. So if you feel like it, start one right after se= nding + the report -- or perform one before sending it, which will tell you to w= hom + the report needs to be sent. + + In case you failed to reproduce a problem with mainline: Is it a problem= that + is not a regression? One you want to see resolved in a stable or longterm + series? If all that is the case, head over to ':ref:`Handling non-regres= sions + only occurring in stable or longterm kernels' `. + + Note: Don't take the requirements in this step lightheartedly, as otherw= ise + there is quite a risk your report will be fruitless or even ignored. + + [:ref:`details `] =20 * Optimize your notes: try to find and write the most straightforward way= to reproduce your issue. Make sure the end result has all the important @@ -230,9 +266,6 @@ After these preparations you'll now enter the main part: * If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consid= er decoding the kernel log to find the line of code that triggered the err= or. =20 - * If your problem is a regression, try to narrow down when the issue was - introduced as much as possible. - * Start to compile the report by writing a detailed description about the issue. Always mention a few things: the latest kernel version you insta= lled for reproducing, the Linux Distribution used, and your notes on how to @@ -257,70 +290,46 @@ After these preparations you'll now enter the main pa= rt: help yourself, if you don't get any help or if it's unsatisfying. =20 =20 -Reporting regressions within a stable and longterm kernel line --------------------------------------------------------------- - -This subsection is for you, if you followed above process and got sent her= e at -the point about regression within a stable or longterm kernel version line= . You -face one of those if something breaks when updating from 5.10.4 to 5.10.5 = (a -switch from 5.9.15 to 5.10.5 does not qualify). The developers want to fix= such -regressions as quickly as possible, hence there is a streamlined process to -report them: - - * Check if the kernel developers still maintain the Linux kernel version - line you care about: go to the `front page of kernel.org - `_ and make sure it mentions - the latest release of the particular version line without an '[EOL]' ta= g. - - * Check the archives of the `Linux stable mailing list - `_ for existing reports. - - * Install the latest release from the particular version line as a vanilla - kernel. Ensure this kernel is not tainted and still shows the problem, = as - the issue might have already been fixed there. If you first noticed the - problem with a vendor kernel, check a vanilla build of the last version - known to work performs fine as well. - - * Send a short problem report to the Linux stable mailing list - (stable@vger.kernel.org) and CC the Linux regressions mailing list - (regressions@lists.linux.dev); if you suspect the cause in a particular - subsystem, CC its maintainer and its mailing list. Roughly describe the - issue and ideally explain how to reproduce it. Mention the first version - that shows the problem and the last version that's working fine. Then - wait for further instructions. +Handling non-regressions only occurring in stable or longterm kernels +--------------------------------------------------------------------- =20 -The reference section below explains each of these steps in more detail. +Follow the next few steps only if the step-by-step guide sent you here. Th= at is +the case when you are (a) facing an issue in the latest release of a still +supported stable or longterm series that (b) you were unable to reproduce = in +the current mainline and (c) is not a regression. If all of that holds tru= e, +follow these steps: =20 +* Be aware: it is possible the issue will not be resolved, as the fix migh= t be + too big or risky to backport. =20 -Reporting issues only occurring in older kernel version lines -------------------------------------------------------------- +* Search Linux' mainline Git repository or `lore + `_ for the change resolving the issue. In = case + you have trouble locating it, consider using a bisection; alternatively = ask + on the list of the affected subsystem for advice while CCing the relevant + maintainers and developers. =20 -This subsection is for you, if you tried the latest mainline kernel as out= lined -above, but failed to reproduce your issue there; at the same time you want= to -see the issue fixed in a still supported stable or longterm series or vend= or -kernels regularly rebased on those. If that is the case, follow these step= s: +* Check if the change is already scheduled to be backported by searching t= he + patch description for a 'stable tag' (a line like 'Cc: + ' and the patch's title in lore.kernel.org: =20 - * Prepare yourself for the possibility that going through the next few st= eps - might not get the issue solved in older releases: the fix might be too = big - or risky to get backported there. + * If the change is already scheduled for backporting, it usually will be + picked up within one or two weeks after being mainlined. Note though, = plans + sometimes change; a comment next to the stable tag might also limit ho= w far + the fix is backported and thus exclude the series you care about. If t= here + are good reasons for this, you are out of luck. If you can't spot any: =20 - * Perform the first three steps in the section "Dealing with regressions - within a stable and longterm kernel line" above. + Send a reply asking the involved developers if backporting to the seri= es is + an option. Note though, the developers might greenlight backporting, b= ut + unwilling to handle the work themselves -- in which case you or somebo= dy + else must test and submit the fix and everything it depends on as expl= ained + in Documentation/process/stable-kernel-rules.rst. =20 - * Search the Linux kernel version control system for the change that fixed - the issue in mainline, as its commit message might tell you if the fix = is - scheduled for backporting already. If you don't find anything that way, - search the appropriate mailing lists for posts that discuss such an iss= ue - or peer-review possible fixes; then check the discussions if the fix was - deemed unsuitable for backporting. If backporting was not considered at - all, join the newest discussion, asking if it's in the cards. - - * One of the former steps should lead to a solution. If that doesn't work - out, ask the maintainers for the subsystem that seems to be causing the - issue for advice; CC the mailing list for the particular subsystem as w= ell - as the stable mailing list. - -The reference section below explains each of these steps in more detail. + * If the change is not scheduled for backporting, search `lore + `_ for the review of the fix and check if + backporting is planned or was rejected. If it is neither, send a reply + asking the involved developers if backporting to the series is an opti= on. + Just as mentioned in the previous paragraph, you might need to handle + backporting on your own. =20 =20 Conclusion of the step-by-step guide @@ -958,212 +967,25 @@ the verification. [:ref:`back to step-by-step guide `] =20 =20 -Make sure your kernel doesn't get enhanced ------------------------------------------- - - *Ensure your system does not enhance its kernels by building additional - kernel modules on-the-fly, which solutions like DKMS might be doing lo= cally - without your knowledge.* - -The risk your issue report gets ignored or rejected dramatically increases= if -your kernel gets enhanced in any way. That's why you should remove or disa= ble -mechanisms like akmods and DKMS: those build add-on kernel modules -automatically, for example when you install a new Linux kernel or boot it = for -the first time. Also remove any modules they might have installed. Then re= boot -before proceeding. - -Note, you might not be aware that your system is using one of these soluti= ons: -they often get set up silently when you install Nvidia's proprietary graph= ics -driver, VirtualBox, or other software that requires a some support from a -module not part of the Linux kernel. That why your might need to uninstall= the -packages with such software to get rid of any 3rd party kernel module. - +.. _verify_repiref: =20 -Regression in stable or longterm kernel? ----------------------------------------- - - *If you are facing a regression within a stable or longterm version li= ne - (say something broke when updating from 5.10.4 to 5.10.5), scroll down= to - 'Dealing with regressions within a stable and longterm kernel line'.* - -Regression within a stable and longterm kernel version line are something = the -Linux developers want to fix badly, as such issues are even more unwanted = than -regression in the main development branch, as they can quickly affect a lo= t of -people. The developers thus want to learn about such issues as quickly as -possible, hence there is a streamlined process to report them. Note, -regressions with newer kernel version line (say something broke when switc= hing -from 5.9.15 to 5.10.5) do not qualify. +Verify the problem with a suitable kernel +----------------------------------------- =20 + *You must report the problem using a kernel suitable for reporting -- so= you + [...] In case of a regression within a stable or longterm kernel, you al= so + must check* [:ref:`... `] =20 -Install a fresh kernel for testing ----------------------------------- +Following the instructions in this step dramatically increases the chance = some +developer will look into the report, as it ensures the bug is actually pre= sent +in a codebase they care about; for regressions in stable or longterm serie= s, +they furthermore determine the right point of contact for the bug, which +depends on whether the problem happens in mainline as well. =20 - *Unless you are already running the latest 'mainline' Linux kernel, be= tter - go and install it for the reporting process. Testing and reporting with - the latest 'stable' Linux can be an acceptable alternative in some - situations; during the merge window that actually might be even the be= st - approach, but in that development phase it can be an even better idea = to - suspend your efforts for a few days anyway. Whatever version you choos= e, - ideally use a 'vanilla' built. Ignoring these advices will dramatically - increase the risk your report will be rejected or ignored.* - -As mentioned in the detailed explanation for the first step already: Like = most -programmers, Linux kernel developers don't like to spend time dealing with -reports for issues that don't even happen with the current code. It's just= a -waste everybody's time, especially yours. That's why it's in everybody's -interest that you confirm the issue still exists with the latest upstream = code -before reporting it. You are free to ignore this advice, but as outlined -earlier: doing so dramatically increases the risk that your issue report m= ight -get rejected or simply ignored. - -In the scope of the kernel "latest upstream" normally means: - - * Install a mainline kernel; the latest stable kernel can be an option, b= ut - most of the time is better avoided. Longterm kernels (sometimes called = 'LTS - kernels') are unsuitable at this point of the process. The next subsect= ion - explains all of this in more detail. - - * The over next subsection describes way to obtain and install such a ker= nel. - It also outlines that using a pre-compiled kernel are fine, but better = are - vanilla, which means: it was built using Linux sources taken straight `= from - kernel.org `_ and not modified or enhanced in any = way. - -Choosing the right version for testing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Head over to `kernel.org `_ to find out which version= you -want to use for testing. Ignore the big yellow button that says 'Latest re= lease' -and look a little lower at the table. At its top you'll see a line startin= g with -mainline, which most of the time will point to a pre-release with a version -number like '5.8-rc2'. If that's the case, you'll want to use this mainline -kernel for testing, as that where all fixes have to be applied first. Do n= ot let -that 'rc' scare you, these 'development kernels' are pretty reliable =E2= =80=94 and you -made a backup, as you were instructed above, didn't you? - -In about two out of every nine to ten weeks, mainline might point you to a -proper release with a version number like '5.7'. If that happens, consider -suspending the reporting process until the first pre-release of the next -version (5.8-rc1) shows up on kernel.org. That's because the Linux develop= ment -cycle then is in its two-week long 'merge window'. The bulk of the changes= and -all intrusive ones get merged for the next release during this time. It's = a bit -more risky to use mainline during this period. Kernel developers are also = often -quite busy then and might have no spare time to deal with issue reports. I= t's -also quite possible that one of the many changes applied during the merge -window fixes the issue you face; that's why you soon would have to retest = with -a newer kernel version anyway, as outlined below in the section 'Duties af= ter -the report went out'. - -That's why it might make sense to wait till the merge window is over. But = don't -to that if you're dealing with something that shouldn't wait. In that case -consider obtaining the latest mainline kernel via git (see below) or use t= he -latest stable version offered on kernel.org. Using that is also acceptable= in -case mainline for some reason does currently not work for you. An in gener= al: -using it for reproducing the issue is also better than not reporting it is= sue -at all. - -Better avoid using the latest stable kernel outside merge windows, as all = fixes -must be applied to mainline first. That's why checking the latest mainline -kernel is so important: any issue you want to see fixed in older version l= ines -needs to be fixed in mainline first before it can get backported, which can -take a few days or weeks. Another reason: the fix you hope for might be too -hard or risky for backporting; reporting the issue again hence is unlikely= to -change anything. - -These aspects are also why longterm kernels (sometimes called "LTS kernels= ") -are unsuitable for this part of the reporting process: they are to distant= from -the current code. Hence go and test mainline first and follow the process -further: if the issue doesn't occur with mainline it will guide you how to= get -it fixed in older version lines, if that's in the cards for the fix in que= stion. - -How to obtain a fresh Linux kernel -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Using a pre-compiled kernel**: This is often the quickest, easiest, and = safest -way for testing =E2=80=94 especially is you are unfamiliar with the Linux = kernel. The -problem: most of those shipped by distributors or add-on repositories are = build -from modified Linux sources. They are thus not vanilla and therefore often -unsuitable for testing and issue reporting: the changes might cause the is= sue -you face or influence it somehow. - -But you are in luck if you are using a popular Linux distribution: for qui= te a -few of them you'll find repositories on the net that contain packages with= the -latest mainline or stable Linux built as vanilla kernel. It's totally okay= to -use these, just make sure from the repository's description they are vanil= la or -at least close to it. Additionally ensure the packages contain the latest -versions as offered on kernel.org. The packages are likely unsuitable if t= hey -are older than a week, as new mainline and stable kernels typically get re= leased -at least once a week. - -Please note that you might need to build your own kernel manually later: t= hat's -sometimes needed for debugging or testing fixes, as described later in this -document. Also be aware that pre-compiled kernels might lack debug symbols= that -are needed to decode messages the kernel prints when a panic, Oops, warnin= g, or -BUG occurs; if you plan to decode those, you might be better off compiling= a -kernel yourself (see the end of this subsection and the section titled 'De= code -failure messages' for details). - -**Using git**: Developers and experienced Linux users familiar with git are -often best served by obtaining the latest Linux kernel sources straight fr= om the -`official development repository on kernel.org -= `_. -Those are likely a bit ahead of the latest mainline pre-release. Don't wor= ry -about it: they are as reliable as a proper pre-release, unless the kernel's -development cycle is currently in the middle of a merge window. But even t= hen -they are quite reliable. - -**Conventional**: People unfamiliar with git are often best served by -downloading the sources as tarball from `kernel.org `= _. - -How to actually build a kernel is not described here, as many websites exp= lain -the necessary steps already. If you are new to it, consider following one = of -those how-to's that suggest to use ``make localmodconfig``, as that tries = to -pick up the configuration of your current kernel and then tries to adjust = it -somewhat for your system. That does not make the resulting kernel any bett= er, -but quicker to compile. - -Note: If you are dealing with a panic, Oops, warning, or BUG from the kern= el, -please try to enable CONFIG_KALLSYMS when configuring your kernel. -Additionally, enable CONFIG_DEBUG_KERNEL and CONFIG_DEBUG_INFO, too; the -latter is the relevant one of those two, but can only be reached if you en= able -the former. Be aware CONFIG_DEBUG_INFO increases the storage space require= d to -build a kernel by quite a bit. But that's worth it, as these options will = allow -you later to pinpoint the exact line of code that triggers your issue. The -section 'Decode failure messages' below explains this in more detail. - -But keep in mind: Always keep a record of the issue encountered in case it= is -hard to reproduce. Sending an undecoded report is better than not reporting -the issue at all. +The step-by-step guide outlines the gist of the required tasks; if you need +more detailed instructions, follow Documentation/admin-guide/verify-bugs-a= nd-bisect-regressions.rst. =20 - -Check 'taint' flag ------------------- - - *Ensure the kernel you just installed does not 'taint' itself when - running.* - -As outlined above in more detail already: the kernel sets a 'taint' flag w= hen -something happens that can lead to follow-up errors that look totally -unrelated. That's why you need to check if the kernel you just installed d= oes -not set this flag. And if it does, you in almost all the cases needs to -eliminate the reason for it before you reporting issues that occur with it= . See -the section above for details how to do that. - - -Reproduce issue with the fresh kernel -------------------------------------- - - *Reproduce the issue with the kernel you just installed. If it doesn't= show - up there, scroll down to the instructions for issues only happening wi= th - stable and longterm kernels.* - -Check if the issue occurs with the fresh Linux kernel version you just -installed. If it was fixed there already, consider sticking with this vers= ion -line and abandoning your plan to report the issue. But keep in mind that o= ther -users might still be plagued by it, as long as it's not fixed in either st= able -and longterm version from kernel.org (and thus vendor kernels derived from -those). If you prefer to use one of those or just want to help their users, -head over to the section "Details about reporting issues only occurring in -older kernel version lines" below. +[:ref:`back to step-by-step guide `] =20 =20 Optimize description to reproduce issue @@ -1239,60 +1061,6 @@ be required to retrieve the relevant details. Don't = worry about that, if that's needed in your case, developers will tell you what to do. =20 =20 -Special care for regressions ----------------------------- - - *If your problem is a regression, try to narrow down when the issue was - introduced as much as possible.* - -Linux lead developer Linus Torvalds insists that the Linux kernel never -worsens, that's why he deems regressions as unacceptable and wants to see = them -fixed quickly. That's why changes that introduced a regression are often -promptly reverted if the issue they cause can't get solved quickly any oth= er -way. Reporting a regression is thus a bit like playing a kind of trump car= d to -get something quickly fixed. But for that to happen the change that's caus= ing -the regression needs to be known. Normally it's up to the reporter to track -down the culprit, as maintainers often won't have the time or setup at han= d to -reproduce it themselves. - -To find the change there is a process called 'bisection' which the document -Documentation/admin-guide/bug-bisect.rst describes in detail. That process -will often require you to build about ten to twenty kernel images, trying = to -reproduce the issue with each of them before building the next. Yes, that = takes -some time, but don't worry, it works a lot quicker than most people assume. -Thanks to a 'binary search' this will lead you to the one commit in the so= urce -code management system that's causing the regression. Once you find it, se= arch -the net for the subject of the change, its commit id and the shortened com= mit id -(the first 12 characters of the commit id). This will lead you to existing -reports about it, if there are any. - -Note, a bisection needs a bit of know-how, which not everyone has, and qui= te a -bit of effort, which not everyone is willing to invest. Nevertheless, it's -highly recommended performing a bisection yourself. If you really can't or -don't want to go down that route at least find out which mainline kernel -introduced the regression. If something for example breaks when switching = from -5.5.15 to 5.8.4, then try at least all the mainline releases in that area = (5.6, -5.7 and 5.8) to check when it first showed up. Unless you're trying to fin= d a -regression in a stable or longterm kernel, avoid testing versions which nu= mber -has three sections (5.6.12, 5.7.8), as that makes the outcome hard to -interpret, which might render your testing useless. Once you found the maj= or -version which introduced the regression, feel free to move on in the repor= ting -process. But keep in mind: it depends on the issue at hand if the develope= rs -will be able to help without knowing the culprit. Sometimes they might -recognize from the report want went wrong and can fix it; other times they= will -be unable to help unless you perform a bisection. - -When dealing with regressions make sure the issue you face is really cause= d by -the kernel and not by something else, as outlined above already. - -In the whole process keep in mind: an issue only qualifies as regression i= f the -older and the newer kernel got built with a similar configuration. This ca= n be -achieved by using ``make olddefconfig``, as explained in more detail by -Documentation/admin-guide/reporting-regressions.rst; that document also -provides a good deal of other information about regressions you might want= to be -aware of. - - Write and send the report ------------------------- =20 @@ -1689,108 +1457,6 @@ easier. And with a bit of luck there might be someo= ne in the team that knows a bit about programming and might be able to write a fix. =20 =20 -Reference for "Reporting regressions within a stable and longterm kernel l= ine" ---------------------------------------------------------------------------= ---- - -This subsection provides details for the steps you need to perform if you = face -a regression within a stable and longterm kernel line. - -Make sure the particular version line still gets support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Check if the kernel developers still maintain the Linux kernel version - line you care about: go to the front page of kernel.org and make sure = it - mentions the latest release of the particular version line without an - '[EOL]' tag.* - -Most kernel version lines only get supported for about three months, as -maintaining them longer is quite a lot of work. Hence, only one per year is -chosen and gets supported for at least two years (often six). That's why y= ou -need to check if the kernel developers still support the version line you = care -for. - -Note, if kernel.org lists two stable version lines on the front page, you -should consider switching to the newer one and forget about the older one: -support for it is likely to be abandoned soon. Then it will get a "end-of-= life" -(EOL) stamp. Version lines that reached that point still get mentioned on = the -kernel.org front page for a week or two, but are unsuitable for testing and -reporting. - -Search stable mailing list -~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Check the archives of the Linux stable mailing list for existing repo= rts.* - -Maybe the issue you face is already known and was fixed or is about to. He= nce, -`search the archives of the Linux stable mailing list -`_ for reports about an issue like yours.= If -you find any matches, consider joining the discussion, unless the fix is -already finished and scheduled to get applied soon. - -Reproduce issue with the newest release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Install the latest release from the particular version line as a vani= lla - kernel. Ensure this kernel is not tainted and still shows the problem,= as - the issue might have already been fixed there. If you first noticed the - problem with a vendor kernel, check a vanilla build of the last version - known to work performs fine as well.* - -Before investing any more time in this process you want to check if the is= sue -was already fixed in the latest release of version line you're interested = in. -This kernel needs to be vanilla and shouldn't be tainted before the issue -happens, as detailed outlined already above in the section "Install a fresh -kernel for testing". - -Did you first notice the regression with a vendor kernel? Then changes the -vendor applied might be interfering. You need to rule that out by performi= ng -a recheck. Say something broke when you updated from 5.10.4-vendor.42 to -5.10.5-vendor.43. Then after testing the latest 5.10 release as outlined in -the previous paragraph check if a vanilla build of Linux 5.10.4 works fine= as -well. If things are broken there, the issue does not qualify as upstream -regression and you need switch back to the main step-by-step guide to repo= rt -the issue. - -Report the regression -~~~~~~~~~~~~~~~~~~~~~ - - *Send a short problem report to the Linux stable mailing list - (stable@vger.kernel.org) and CC the Linux regressions mailing list - (regressions@lists.linux.dev); if you suspect the cause in a particular - subsystem, CC its maintainer and its mailing list. Roughly describe the - issue and ideally explain how to reproduce it. Mention the first versi= on - that shows the problem and the last version that's working fine. Then - wait for further instructions.* - -When reporting a regression that happens within a stable or longterm kernel -line (say when updating from 5.10.4 to 5.10.5) a brief report is enough for -the start to get the issue reported quickly. Hence a rough description to = the -stable and regressions mailing list is all it takes; but in case you suspe= ct -the cause in a particular subsystem, CC its maintainers and its mailing li= st -as well, because that will speed things up. - -And note, it helps developers a great deal if you can specify the exact ve= rsion -that introduced the problem. Hence if possible within a reasonable time fr= ame, -try to find that version using vanilla kernels. Let's assume something bro= ke when -your distributor released a update from Linux kernel 5.10.5 to 5.10.8. The= n as -instructed above go and check the latest kernel from that version line, say -5.10.9. If it shows the problem, try a vanilla 5.10.5 to ensure that no pa= tches -the distributor applied interfere. If the issue doesn't manifest itself th= ere, -try 5.10.7 and then (depending on the outcome) 5.10.8 or 5.10.6 to find the -first version where things broke. Mention it in the report and state that = 5.10.9 -is still broken. - -What the previous paragraph outlines is basically a rough manual 'bisectio= n'. -Once your report is out your might get asked to do a proper one, as it all= ows to -pinpoint the exact change that causes the issue (which then can easily get -reverted to fix the issue quickly). Hence consider to do a proper bisection -right away if time permits. See the section 'Special care for regressions'= and -the document Documentation/admin-guide/bug-bisect.rst for details how to -perform one. In case of a successful bisection add the author of the culpr= it to -the recipients; also CC everyone in the signed-off-by chain, which you fin= d at -the end of its commit message. - - Reference for "Reporting issues only occurring in older kernel version lin= es" --------------------------------------------------------------------------= --- =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 231252DCF50; Sun, 26 Oct 2025 12:42:33 +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=1761482559; cv=none; b=LsYCS4FtXFWPpHwIJj55sgPrb24vx6TfqDRpR175c+UVLLU5cilZ9y1rOCVcsilJsYLvtLrY4+VSorBs/8xHLZtLIDbG1j3A5j18kP66uDZRC5Akw40OH62jMe9VrDTArn7yExggy6XKwZEaUWeDCW//Rr2++Em2cdcMwXryAEo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482559; c=relaxed/simple; bh=YPmz9plxeC1YEcFAWI17S4yEgIf+VNJKzQ5SC6730bM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hIRzn0ar26uKSoN+2uaWzhubYfF2t4toJJO3cqKvyL0Ds3UoRiC43rSMsxQm+G0eOPFrByabsb8SL7tGuCMPQMGEX/9LRwm/1LXl68BXmfQTZYNFuYzM2F7v+WT67iZN6b39yJ2jWIue3hVCHRw5MO5IPXDgxbEBqhjqvruOkcU= 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=AehCcECH; 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="AehCcECH" 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=Xl7EbKxVssEXZJh8Rfnajk+ePVuHpmu9Mxi6gIB7sbs=; t=1761482554; x=1761914554; b=AehCcECHHGj7CGEj59Ae1dQLU2Ijx4/jffdmjsx/fPw+ERI4S5ZNiN8GhIVST pc6igRHKLLyD7czlsoeUucTe0AVXumx928Zb5prlvHi4APx+jDAhwQ8d+egcZbPFSOWSiU44sy0Yo me4LsdTq+uDBuPQHRpI1ks3iJ3hSkaQeF1Z4gL5P8N+gKRZTgUHC5t8jWppxDM1mI3PQSfpiPv1zP BGGwmVMSbGZCJovVRuz3/36JBB0vBOeuv2RjwtyovzjtfGqDALItZNV6DJYiktI5REWAbnoWGLY0m kwA02lDXOSwXMwHXJe0le7uIufLl5yvRRGEPyFSVIRZsVMG6hw==; 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 1vD04u-001mZC-06; Sun, 26 Oct 2025 13:42:32 +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 25/30] docs: reporting-issues: improve text on non-regressions in stable Date: Sun, 26 Oct 2025 13:42:16 +0100 Message-ID: <0a3548a6b5d8ca87c9d81838d84afeb619a6985e.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;1761482554;2f8dc1da; X-HE-SMSGID: 1vD04u-001mZC-06 Content-Type: text/plain; charset="utf-8" Fine-tune the instructions about handling non-regressions only occurring in stable or longterm kernels. This removes the accompanying text in the reference section to shorten things somewhat: this case is rare and the instructions in the step-by-step guide cover all the important bits now. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 129 ++---------------- 1 file changed, 9 insertions(+), 120 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 9611514d10414e..a78060098c59f0 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -299,29 +299,29 @@ supported stable or longterm series that (b) you were= unable to reproduce in the current mainline and (c) is not a regression. If all of that holds tru= e, follow these steps: =20 -* Be aware: it is possible the issue will not be resolved, as the fix migh= t be +* Be aware: It is possible the issue will not be resolved, as the fix migh= t be too big or risky to backport. =20 -* Search Linux' mainline Git repository or `lore +* Search Linux's mainline Git repository or `lore `_ for the change resolving the issue. In = case - you have trouble locating it, consider using a bisection; alternatively = ask + you have trouble locating it, consider using a bisection; alternatively,= ask on the list of the affected subsystem for advice while CCing the relevant maintainers and developers. =20 * Check if the change is already scheduled to be backported by searching t= he - patch description for a 'stable tag' (a line like 'Cc: - ' and the patch's title in lore.kernel.org: + patch description for a 'stable tag' (e.g., a line like 'Cc: + ') and the patch's title in lore.kernel.org: =20 - * If the change is already scheduled for backporting, it usually will be - picked up within one or two weeks after being mainlined. Note though, = plans + * If the change is already scheduled for backporting, it will usually be + picked up within one or two weeks after being mainlined. Note, though,= plans sometimes change; a comment next to the stable tag might also limit ho= w far the fix is backported and thus exclude the series you care about. If t= here are good reasons for this, you are out of luck. If you can't spot any: =20 Send a reply asking the involved developers if backporting to the seri= es is - an option. Note though, the developers might greenlight backporting, b= ut + an option. Note, though, the developers might greenlight backporting, = but unwilling to handle the work themselves -- in which case you or somebo= dy - else must test and submit the fix and everything it depends on as expl= ained + else must test and submit the fix and everything it depends on, as exp= lained in Documentation/process/stable-kernel-rules.rst. =20 * If the change is not scheduled for backporting, search `lore @@ -1457,117 +1457,6 @@ easier. And with a bit of luck there might be someo= ne in the team that knows a bit about programming and might be able to write a fix. =20 =20 -Reference for "Reporting issues only occurring in older kernel version lin= es" ---------------------------------------------------------------------------= --- - -This section provides details for the steps you need to take if you could = not -reproduce your issue with a mainline kernel, but want to see it fixed in o= lder -version lines (aka stable and longterm kernels). - -Some fixes are too complex -~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Prepare yourself for the possibility that going through the next few = steps - might not get the issue solved in older releases: the fix might be too= big - or risky to get backported there.* - -Even small and seemingly obvious code-changes sometimes introduce new and -totally unexpected problems. The maintainers of the stable and longterm ke= rnels -are very aware of that and thus only apply changes to these kernels that a= re -within rules outlined in Documentation/process/stable-kernel-rules.rst. - -Complex or risky changes for example do not qualify and thus only get appl= ied -to mainline. Other fixes are easy to get backported to the newest stable a= nd -longterm kernels, but too risky to integrate into older ones. So be aware = the -fix you are hoping for might be one of those that won't be backported to t= he -version line your care about. In that case you'll have no other choice the= n to -live with the issue or switch to a newer Linux version, unless you want to -patch the fix into your kernels yourself. - -Common preparations -~~~~~~~~~~~~~~~~~~~ - - *Perform the first three steps in the section "Reporting issues only - occurring in older kernel version lines" above.* - -You need to carry out a few steps already described in another section of = this -guide. Those steps will let you: - - * Check if the kernel developers still maintain the Linux kernel version = line - you care about. - - * Search the Linux stable mailing list for exiting reports. - - * Check with the latest release. - - -Check code history and search for existing discussions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Search the Linux kernel version control system for the change that fi= xed - the issue in mainline, as its commit message might tell you if the fix= is - scheduled for backporting already. If you don't find anything that way, - search the appropriate mailing lists for posts that discuss such an is= sue - or peer-review possible fixes; then check the discussions if the fix w= as - deemed unsuitable for backporting. If backporting was not considered at - all, join the newest discussion, asking if it's in the cards.* - -In a lot of cases the issue you deal with will have happened with mainline= , but -got fixed there. The commit that fixed it would need to get backported as = well -to get the issue solved. That's why you want to search for it or any -discussions abound it. - - * First try to find the fix in the Git repository that holds the Linux ke= rnel - sources. You can do this with the web interfaces `on kernel.org - `_ - or its mirror `on GitHub `_; if you = have - a local clone you alternatively can search on the command line with ``g= it - log --grep=3D``. - - If you find the fix, look if the commit message near the end contains a - 'stable tag' that looks like this: - - Cc: # 5.4+ - - If that's case the developer marked the fix safe for backporting to ver= sion - line 5.4 and later. Most of the time it's getting applied there within = two - weeks, but sometimes it takes a bit longer. - - * If the commit doesn't tell you anything or if you can't find the fix, l= ook - again for discussions about the issue. Search the net with your favorite - internet search engine as well as the archives for the `Linux kernel - developers mailing list `_. Also read the - section `Locate kernel area that causes the issue` above and follow the - instructions to find the subsystem in question: its bug tracker or mail= ing - list archive might have the answer you are looking for. - - * If you see a proposed fix, search for it in the version control system = as - outlined above, as the commit might tell you if a backport can be expec= ted. - - * Check the discussions for any indicators the fix might be too risky t= o get - backported to the version line you care about. If that's the case you= have - to live with the issue or switch to the kernel version line where the= fix - got applied. - - * If the fix doesn't contain a stable tag and backporting was not discu= ssed, - join the discussion: mention the version where you face the issue and= that - you would like to see it fixed, if suitable. - - -Ask for advice -~~~~~~~~~~~~~~ - - *One of the former steps should lead to a solution. If that doesn't wo= rk - out, ask the maintainers for the subsystem that seems to be causing the - issue for advice; CC the mailing list for the particular subsystem as = well - as the stable mailing list.* - -If the previous three steps didn't get you closer to a solution there is o= nly -one option left: ask for advice. Do that in a mail you sent to the maintai= ners -for the subsystem where the issue seems to have its roots; CC the mailing = list -for the subsystem as well as the stable mailing list (stable@vger.kernel.o= rg). - - Appendix: additional background information =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 22F212DCF4E; Sun, 26 Oct 2025 12:42:34 +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=1761482556; cv=none; b=l0HlwR9AIEdJGLabnjbagR1sTvo5yao9CV4QblNfF7YFA1vWUSzNIy76/QFJWhkkySPzv3mq42gTj4EVFZkS4NJ+pKMbeYs31tBRnpSifPDN+p6Uv4k34sjjVHLnVwe112ThuH62ctC9teHons7IczJi94gbRy2jQ4Ukueefy+4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482556; c=relaxed/simple; bh=ftrjxyR5SRqa7HLu+jbXUUvmYzdPS+hzpbZq2tjBS6U=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=fJqVgF4oKOkwIu/oLad/e+njSH220qKDlnHeQRFvtvh6RgVrlNobnzrcP/Uk0DU49j1ZCgmRIETEnt3uaaTh7zSo6HcrJjje+JLBPuVAsHugvsazVk3x+Qdj1llRWpMWuZbQoD05lUPYMP+M0NEz8hWkNukYz1wmCg6DD2ttDBw= 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=MKfz35Jr; 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="MKfz35Jr" 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=qAm9hVLNKsdEv5v/8w3e/Zz2emv2ug/0HzuP0mkDOgU=; t=1761482554; x=1761914554; b=MKfz35Jr5C3OPvJRA7/z/rg2go32cBGeXv08ZjWCXSmLvoYgLBOBttuNr/Oc8 GQQOoM+qSprEp1VZhqfw4wfo45B1zOdhSwaYAc4O3dbaOmEL1V/TkkHc0cU5qhORAaOxCy6m9U7Yx gEPFQj/xHs/RsEJdpwNSynAcrImw+//JcBoTO7gmw0b5QzQ/xYu56mJxzazZfP8KpNdBe8vEEv1Tt gM+/sdTL4tJ13nAVmQtpH6Ez0M6gS8CPDvEmyZU7hdk+numn2BQjxzrmoBn9xj73cTv3xzcK4/aLP QekhJ73K5T7qRr4/XCZRNGbiaWpLW0yj2bkpsW3GRa36icInTQ==; 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 1vD04u-001mZC-1A; Sun, 26 Oct 2025 13:42:32 +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 26/30] docs: reporting-issues: improve text on second search Date: Sun, 26 Oct 2025 13:42:17 +0100 Message-ID: <91a969bd0db253f59f579ec3a080404029756d3b.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;1761482554;2f8dc1da; X-HE-SMSGID: 1vD04u-001mZC-1A Content-Type: text/plain; charset="utf-8" Fine-tune the instructions about searching lore again while dropping the text on optimizing the write-up how to reproduce the issue: this is left to a later step now. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 38 ++++++++++--------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index a78060098c59f0..aad98ccb49add8 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -257,11 +257,17 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 - * Optimize your notes: try to find and write the most straightforward way= to - reproduce your issue. Make sure the end result has all the important - details, and at the same time is easy to read and understand for others - that hear about it for the first time. And if you learned something in = this - process, consider searching again for existing reports about the issue. +.. _checkloretwo_repisbs: + +* If you performed a bisection or learned anything new about the bug while + following this guide so far, search once more for earlier reports + and fixes. In the bisection case, you want to search + `lore `_ for the culprit's mainline comm= it-id + abbreviated to seven characters immediately followed by an asterisk (e.g= ., + '`1f2e3d4 `_'); if that does = not + produce any valuable insights, search for the commit's title, too. + + [:ref:`details `] =20 * If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consid= er decoding the kernel log to find the line of code that triggered the err= or. @@ -988,23 +994,19 @@ more detailed instructions, follow Documentation/admi= n-guide/verify-bugs-and-bis [:ref:`back to step-by-step guide `] =20 =20 -Optimize description to reproduce issue ---------------------------------------- +.. _checkloretwo_repiref: =20 - *Optimize your notes: try to find and write the most straightforward w= ay to - reproduce your issue. Make sure the end result has all the important - details, and at the same time is easy to read and understand for others - that hear about it for the first time. And if you learned something in= this - process, consider searching again for existing reports about the issue= .* +Search again +------------ =20 -An unnecessarily complex report will make it hard for others to understand= your -report. Thus try to find a reproducer that's straight forward to describe = and -thus easy to understand in written form. Include all important details, bu= t at -the same time try to keep it as short as possible. + *If you performed a bisection or learned anything new about the bug + while following this guide so far, search once more* [:ref:`... `] =20 -In this in the previous steps you likely have learned a thing or two about= the +During the previous step you likely have learned a thing or two about the issue you face. Use this knowledge and search again for existing reports -instead you can join. +and potential fixes. + +[:ref:`back to step-by-step guide `] =20 =20 Decode failure messages --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 7B02F2DCF65; Sun, 26 Oct 2025 12:42:34 +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=1761482557; cv=none; b=SPYMryORFh2lOqbKf0rS+fOZsj9T2VTewdmG7cr3cJXPM0QLKtAr4mdH68u9uHhqBxXpVbOMjRPdpqj43XYwM8OXQo6bDspP4iSdbiaPunVIOqS7/2jcfgwao7p4NKn5jhUcLEfaXQWPXQhOcZlMwlxUDmuFE5tke/ZaQeOhmhE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482557; c=relaxed/simple; bh=kKbNh5P3MB7UNe2n6wRJ8m4EFNbtUTJ0tM46QLtzYCs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=N3bLT+J/YWwXSEq2Q00e7uiKdJJpD/i6ZDw64ZL7H+dZPGNW9DTVMwgRoKYi8jxPTUPV5WBBO/059Ji0AX/ttdDDspjtDAwQ2M+lWVKhnZqWKaOdtsfNdodvHxunmBELf89zWJlG72LhkqC4j7F7Ba6JDkdTUfsCBRTYklB+p4I= 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=grqmNnf2; 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="grqmNnf2" 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=7xfO2yVPgMJsrmePB23iI1EzaVJiMZt5mKtEwJsE4MI=; t=1761482554; x=1761914554; b=grqmNnf2Ms/H1kcyHR12RYfKEx4v09dW3XShe6XbsPSZ340fiPsWOT43pEiXk O5AkZss+wG94bhL/WW9PE0R0YenVplBwBmT5Qxx93AiRae07kUMiNTGduXJUaXAl4lZpN9WxY9t0/ JeaZNK8kdzsWNfzpnAs83HagRpPaHQuNQ6wBm66yuoV8+JzRONCWOySM0AmYT1cQYkWw9TD3mfLlD LwIp/mWs4okBUfOuddNdUA0FLOTV+4zqhDjoU871XXExW9c6zxKRkGNvjxOOeaZLR+LiwWxjtYxMT lmq/8K2aIgNX2DVIbGYPfvY2xCGFnvC9b+El9UGBn7y8t7gNVw==; 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 1vD04u-001mZC-2A; Sun, 26 Oct 2025 13:42:32 +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 27/30] docs: reporting-issues: make collecting files a separate step Date: Sun, 26 Oct 2025 13:42:18 +0100 Message-ID: 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;1761482554;2f8dc1da; X-HE-SMSGID: 1vD04u-001mZC-2A Content-Type: text/plain; charset="utf-8" Make collecting files a separate step and tone down the need to decode stack traces somewhat. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 158 +++++++++--------- 1 file changed, 79 insertions(+), 79 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index aad98ccb49add8..5c991163039f82 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -269,8 +269,34 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 - * If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consid= er - decoding the kernel log to find the line of code that triggered the err= or. +.. _attachments_repisbs: + +* Collect relevant files to supply with the report. + + It almost always is wise to store the log messages (``journalctl -k``) f= rom + the kernel used for the verification to a file. In case of a regression, + create a file with log messages from a working kernel, too. + + What else is appropriate to supply depends on your problem. In case of b= uild + errors, the build configuration (the '.config' file) used for the verifi= cation + is important to provide. Other times it is wise to include separate files + with the output from commands such as ``lsblk``, ``lspci -nn``, ``lsusb.= py``, + ``alsa-info.sh``, or ``grep -s '' /sys/class/dmi/id/*``; occasionally the + output of ``lscpu``, ``lsirq``, ``lsmod``, ``sudo lspci -vvv``, or ``lss= csi`` + makes sense, too. + + Only compress files larger than a megabyte. Do not use an archiver to pa= ckage + multiple files together. + + If you later have to file the report in a bug tracker, attach the files.= If + you have to email it, attach them when they in total are smaller than 250 + KByte; if they are bigger, attach only the most relevant and send the re= st in + a reply-to-all to your own report. Alternatively, create a ticket in + `bugzilla.kernel.org `_ with a brief note = that + the ticket is only meant to store files used in a mailed report; attach = the + files there and later link to them in your report. + + [:ref:`details `] =20 * Start to compile the report by writing a detailed description about the issue. Always mention a few things: the latest kernel version you insta= lled @@ -1009,58 +1035,77 @@ and potential fixes. [:ref:`back to step-by-step guide `] =20 =20 +.. _attachments_repiref: + +Collect files to provide +------------------------ + + *Collect relevant files to supply with the report.* [:ref:`... `] + +The developers will usually ask for files with details about your system, = as +what is needed highly depends on the nature of the problem. But it is often +wise to provide at least the kernel log and maybe a few things along with = the +report, as outlined in the step-by-step guide. + +When collecting the kernel's log messages with ``dmesg``, make sure they s= tart +with a line like 'Linux version 5.8-1 (foobar@example.com) (gcc (GCC) 10.2= .1, +GNU ld version 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020'. The kernel disca= rded +messages from the first boot phase already if it is missing. In that case, +instead consider using ``journalctl -k``; alternatively, reboot and reprod= uce +the issue, before calling ``dmesg`` right afterwards. + +In case the kernel's log messages contain a 'panic', 'Oops', 'warning', or +'BUG', you might want to decode them as described below if that is easy fo= r you +-- but that is optional, as many bugs can be solved without this. + +On many Linux distributions the tools mentioned by the guide are installed= by +default, except maybe ``alsa-info.sh``, which `the sound subsystem develop= ers +provide `_. + + Decode failure messages ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ =20 - *If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', cons= ider - decoding the kernel log to find the line of code that triggered the er= ror.* +A 'panic', 'Oops', 'warning', or 'BUG' includes a stack trace, which conta= ins +addresses that allow pinpointing the exact path to the line in your kernel= 's +source code that triggered the issue. Many bugs can be resolved without +decoding these addresses, but for some it is helpful or required. =20 -When the kernel detects an internal problem, it will log some information = about -the executed code. This makes it possible to pinpoint the exact line in the -source code that triggered the issue and shows how it was called. But that= only -works if you enabled CONFIG_DEBUG_INFO and CONFIG_KALLSYMS when configuring -your kernel. If you did so, consider to decode the information from the -kernel's log. That will make it a lot easier to understand what lead to the -'panic', 'Oops', 'warning', or 'BUG', which increases the chances that som= eone -can provide a fix. +That is why it is fine to report problems without bothering about this, but +when asked for this, try to decode the stack trace. Note: This requires a +kernel build with CONFIG_DEBUG_INFO and CONFIG_KALLSYMS enabled. =20 -Decoding can be done with a script you find in the Linux source tree. If y= ou -are running a kernel you compiled yourself earlier, call it like this:: +Usually you want to decode using a script shipped in the Linux sources. If= you +are running a kernel you compiled yourself, call it like this:: =20 - [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stac= ktrace.sh ./linux-5.10.5/vmlinux + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktra= ce.sh ./linux-5.10.5/vmlinux =20 -If you are running a packaged vanilla kernel, you will likely have to inst= all -the corresponding packages with debug symbols. Then call the script (which= you -might need to get from the Linux sources if your distro does not package i= t) -like this:: +If you are running a packaged kernel, you will likely have to install pack= ages +with the corresponding debug symbols. Then call the script (which you migh= t need +to fetch from the Linux sources if your distro does not package it) like t= his:: =20 - [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stac= ktrace.sh \ - /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/ker= nels/5.10.10-4.1.x86_64/ + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktra= ce.sh \ + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/debug/ke= rnel-5.10.10-4.1.x86_64/ =20 The script will work on log lines like the following, which show the addre= ss of the code the kernel was executing when the error occurred:: =20 - [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] + [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] =20 Once decoded, these lines will look like this:: =20 - [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.1= 0.5/test-module/test-module.c:16) test_module + [ 68.387301] RIP: 0010:test_module_init (/home/user/linux-5.10.5/test= -module/test-module.c:16) test_module =20 In this case the executed code was built from the file -'~/linux-5.10.5/test-module/test-module.c' and the error occurred by the +'~/linux-5.10.5/test-module/test-module.c' and the error occurred during t= he instructions found in line '16'. =20 The script will similarly decode the addresses mentioned in the section -starting with 'Call trace', which show the path to the function where the -problem occurred. Additionally, the script will show the assembler output = for -the code section the kernel was executing. +starting with 'Call trace', which shows the path to the function where the +problem occurred. The script, furthermore, will show the assembler output = for +the code section the kernel was executing at that time. =20 -Note, if you can't get this to work, simply skip this step and mention the -reason for it in the report. If you're lucky, it might not be needed. And = if it -is, someone might help you to get things going. Also be aware this is just= one -of several ways to decode kernel stack traces. Sometimes different steps w= ill -be required to retrieve the relevant details. Don't worry about that, if t= hat's -needed in your case, developers will tell you what to do. +[:ref:`back to step-by-step guide `] =20 =20 Write and send the report @@ -1119,46 +1164,12 @@ but there are some things you should include always: * if you are dealing with a regression and performed a bisection, mention= the subject and the commit-id of the change that is causing it. =20 -In a lot of cases it's also wise to make two more things available to those -that read your report: - - * the configuration used for building your Linux kernel (the '.config' fi= le) - - * the kernel's messages that you get from ``dmesg`` written to a file. Ma= ke - sure that it starts with a line like 'Linux version 5.8-1 - (foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version 2.34) #1 SMP Mon= Aug - 3 14:54:37 UTC 2020' If it's missing, then important messages from the = first - boot phase already got discarded. In this case instead consider using - ``journalctl -b 0 -k``; alternatively you can also reboot, reproduce the - issue and call ``dmesg`` right afterwards. - -These two files are big, that's why it's a bad idea to put them directly i= nto -your report. If you are filing the issue in a bug tracker then attach them= to -the ticket. If you report the issue by mail do not attach them, as that ma= kes -the mail too large; instead do one of these things: - - * Upload the files somewhere public (your website, a public file paste - service, a ticket created just for this purpose on `bugzilla.kernel.org - `_, ...) and include a link to them in yo= ur - report. Ideally use something where the files stay available for years,= as - they could be useful to someone many years from now; this for example c= an - happen if five or ten years from now a developer works on some code tha= t was - changed just to fix your issue. - - * Put the files aside and mention you will send them later in individual - replies to your own mail. Just remember to actually do that once the re= port - went out. ;-) - Things that might be wise to provide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 Depending on the issue you might need to add more background data. Here ar= e a few suggestions what often is good to provide: =20 - * If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the ke= rnel, - include it. If you can't copy'n'paste it, try to capture a netconsole t= race - or at least take a picture of the screen. - * If the issue might be related to your computer hardware, mention what k= ind of system you use. If you for example have problems with your graphics = card, mention its manufacturer, the card's model, and what chip is uses. If i= t's a @@ -1178,17 +1189,6 @@ few suggestions what often is good to provide: its driver. If you have a filesystem issue, mention the version of corresponding filesystem utilities (e2fsprogs, btrfs-progs, xfsprogs, .= ..). =20 - * Gather additional information from the kernel that might be of interest= . The - output from ``lspci -nn`` will for example help others to identify what - hardware you use. If you have a problem with hardware you even might wa= nt to - make the output from ``sudo lspci -vvv`` available, as that provides - insights how the components were configured. For some issues it might be - good to include the contents of files like ``/proc/cpuinfo``, - ``/proc/ioports``, ``/proc/iomem``, ``/proc/modules``, or - ``/proc/scsi/scsi``. Some subsystem also offer tools to collect relevant - information. One such tool is ``alsa-info.sh`` `which the audio/sound - subsystem developers provide `_. - Those examples should give your some ideas of what data might be wise to attach, but you have to think yourself what will be helpful for others to = know. Don't worry too much about forgetting something, as developers will ask for --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 D8B1E2DD5EF; Sun, 26 Oct 2025 12:42:34 +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=1761482558; cv=none; b=EAbKX6oHs+lb6pqFRSg7ucWB9rvM60JRUrABpwvJw4qi5msYe+g/ussI94uHs8MbBOyJ+mElFNCNh7lC2e0dITsiUBwQtzebUfN+XzcOJVm71YiS6J8zUKnVdmO1cWSscqu5Uef5qKA9huZVp3UAHoaZzm6Ey1sifG8oYToR69M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482558; c=relaxed/simple; bh=IqDhGtp4nyvxdpoe48xN9U6qWwQ3W54JbdWSQG/FjaQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=iKiRP2ExloaR4ZSxq1tHyVUMmovgkbyTWT4QQbVxgiaG0+5b6VGREm1X7YnZbHMV2V2CiWbGqt0lplkpQJhf9Qr2biUN7aNj1CacmQ3Bmm9Y05NFy4LQ/fITm8JAzdyxDnoJ17cq5ZqKIQF0TckDYUuKMbmz0XEta/kuQT81Wds= 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=APpdyciq; 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="APpdyciq" 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=z/mmDtnORp4tMTfolU1iwiCKThwrxaag3p5onqizLFY=; t=1761482554; x=1761914554; b=APpdyciqkedRsoanh/bqcCZ5Bg+QLvH6SboUCHDROA6uxyBvzFNKhZvoqiFHY z12vwkjWA8dRs61qnqRdZgdiA/2sUf3nw6x4auCnv9SPnMNTpIO5Pyvp1QKaVJgjaz6coATSDX1Z3 8iFfIOhKiaSxaM7xB8gzFEr0gJJHg0DhQl3zGepezHMb0rmjUrhNq4plr51OoU9wAGdc5Zm55ZJx7 hlb0o6PYP/7z5nB6e3rAUn6uVitlD4mlnnEyYV/ybq3IDFkTT8T4vMyAMYfB/jebUVv4cEsaIVTRU GqNUocYCLpgABZ2/sqgZDvUlwvF7TiewvktA0wd2v9v8AsXIIg==; 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 1vD04u-001mZC-3A; Sun, 26 Oct 2025 13:42:33 +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 28/30] docs: reporting-issues: separate steps for optimizing and submitting reports Date: Sun, 26 Oct 2025 13:42:19 +0100 Message-ID: <13f6dd4470f388220cc559d88afc490aa1c8cd12.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;1761482555;32bd3f7a; X-HE-SMSGID: 1vD04u-001mZC-3A Content-Type: text/plain; charset="utf-8" Make optimizing and submitting reports separate steps. The latter now needs to cover regressions as well, which earlier was handled by a separate section. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 341 ++++++++++-------- 1 file changed, 199 insertions(+), 142 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 5c991163039f82..c147191a7d0987 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -298,21 +298,79 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 - * Start to compile the report by writing a detailed description about the - issue. Always mention a few things: the latest kernel version you insta= lled - for reproducing, the Linux Distribution used, and your notes on how to - reproduce the issue. Ideally, make the kernel's build configuration - (.config) and the output from ``dmesg`` available somewhere on the net = and - link to it. Include or upload all other information that might be relev= ant, - like the output/screenshot of an Oops or the output from ``lspci``. Once - you wrote this main part, insert a normal length paragraph on top of it - outlining the issue and the impact quickly. On top of this add one sent= ence - that briefly describes the problem and gets people to read on. Now give= the - thing a descriptive title or subject that yet again is shorter. Then yo= u're - ready to send or file the report like the MAINTAINERS file told you, un= less - you are dealing with one of those 'issues of high priority': they need - special care which is explained in 'Special handling for high priority - issues' below. +.. _compile_repisbs: + +* Prepare and optimize the report. + + Start by writing a text describing the problem. Ensure it contains all t= he + important bits directly so that readers do not have to open attachments = or + follow links to understand roughly what the report is about -- you thus = might + want to copy error messages and similarly important parts from supplied = files + into the text. + + Early on in the text, mention the distribution and kernel version used f= or the + bug verification. + + In case of a regression, start the subject with '[REGRESSION]'. Furtherm= ore, + specify early in the text the latest working versions and all known to be + broken; if you performed a bisection, mention the culprit's commit-id, t= itle, + and authors instead. + + Mention the Linux distribution used and other aspects of your environment + that might be relevant, like the machine's model name, the hardware + components involved, or the version of related userspace drivers. + + Make sure to not overload the report with a long problem description, too + many details, or many attachments: Developers will ask for additional + information when needed. + + Now write a subject, which is the only thing most people will read -- he= nce + try hard to make it as descriptive as possible without making it overly = long, + as that is your best chance to grab people's attention. Your second best + chance is the first paragraph. If your problem description is longer tha= n two + or three paragraphs, you thus want to create a small intro paragraph + describing the gist of the problem; if it is shorter, optimize the early + sentences. + + At the end, review and optimize the report once more to make it as + straightforward as possible while ensuring the problem is easy to grasp = for + people new to it. + + [:ref:`details `] + +.. _submit_repisbs: + +* Submit your report in the appropriate way, which depends on the outcome = of + the verification and the MAINTAINERS entry. + + * Are you facing a regression within a stable or longterm kernel series = you + were unable to reproduce with a fresh mainline kernel? Then report it = by + email to the stable team while CCing the regressions list (To: Greg + Kroah-Hartman , Sasha Levin ; + CC: stable@vger.kernel.org, regressions@lists.linux.dev); if you perfo= rmed a + bisection, CC everyone in the culprit's 'Signed-off-by' chain, too. + + * In all other cases, submit the report as specified in MAINTAINERS while + keeping Documentation/process/security-bugs.rst in mind in case you de= al + with a security issue: + + * If that means reporting by email, CC linux-kernel@vger.kernel.org. I= n case + of a regression, CC regressions@lists.linux.dev, too -- and when the + culprit is known, also everyone in its 'Signed-off-by' chain, while + addressing the email to the culprit's author. + + * If that means submitting a regression to a bug tracker, perform + one more thing afterwards: Write a short heads-up email with a link = to the + report to regressions@lists.linux.dev -- and if the culprit is known= , CC + everyone that signed it off, while addressing the email to the culpr= it's + author. + + Whichever way it is, in case you sent the brief inquiry mentioned initia= lly + to the regressions list, try to keep that discussion involved: Either se= nd + your report as a reply to the earlier inquiry while adding relevant part= ies + or send a quick reply-to-self with a link to the proper report. + + [:ref:`details `] =20 * Wait for reactions and keep the thing rolling until you can accept the outcome in one way or the other. Thus react publicly and in a timely ma= nner @@ -1108,166 +1166,165 @@ the code section the kernel was executing at that= time. [:ref:`back to step-by-step guide `] =20 =20 -Write and send the report -------------------------- - - *Start to compile the report by writing a detailed description about t= he - issue. Always mention a few things: the latest kernel version you inst= alled - for reproducing, the Linux Distribution used, and your notes on how to - reproduce the issue. Ideally, make the kernel's build configuration - (.config) and the output from ``dmesg`` available somewhere on the net= and - link to it. Include or upload all other information that might be rele= vant, - like the output/screenshot of an Oops or the output from ``lspci``. On= ce - you wrote this main part, insert a normal length paragraph on top of it - outlining the issue and the impact quickly. On top of this add one sen= tence - that briefly describes the problem and gets people to read on. Now giv= e the - thing a descriptive title or subject that yet again is shorter. Then y= ou're - ready to send or file the report like the MAINTAINERS file told you, u= nless - you are dealing with one of those 'issues of high priority': they need - special care which is explained in 'Special handling for high priority - issues' below.* - -Now that you have prepared everything it's time to write your report. How = to do -that is partly explained by the three documents linked to in the preface a= bove. -That's why this text will only mention a few of the essentials as well as -things specific to the Linux kernel. - -There is one thing that fits both categories: the most crucial parts of yo= ur -report are the title/subject, the first sentence, and the first paragraph. -Developers often get quite a lot of mail. They thus often just take a few -seconds to skim a mail before deciding to move on or look closer. Thus: the -better the top section of your report, the higher are the chances that som= eone -will look into it and help you. And that is why you should ignore them for= now -and write the detailed report first. ;-) +.. _compile_repiref: + +Prepare and optimize the report +------------------------------- + + *Prepare and optimize the report.* [:ref:`... `] + +Most developers just take a few seconds to skim a report before deciding +between taking a closer look or moving on, as they receive a ton of messag= es. +That is why the title/subject, the first sentence, and the three or four +following it are crucial. + +People will also stop reading if the report's text is long or hard to foll= ow; +the same is true if crucial information is not at hand. So be sure to desc= ribe +things as short, straightforward, and simple as possible while providing +everything important. + +How to do that is partly explained by the three documents linked to in the +reference section's intro. The next few subsections thus will only mention= a +few essentials as well as things specific to the Linux kernel. + =20 Things each report should mention ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Describe in detail how your issue happens with the fresh vanilla kernel you -installed. Try to include the step-by-step instructions you wrote and opti= mized -earlier that outline how you and ideally others can reproduce the issue; in -those rare cases where that's impossible try to describe what you did to -trigger it. +Describe the problem while mentioning all the important details about the +environment others might need to fully understand the issue.: + +* The output from ``uname -r`` from the Linux kernel used for the verifica= tion. =20 -Also include all the relevant information others might need to understand = the -issue and its environment. What's actually needed depends a lot on the iss= ue, -but there are some things you should include always: +* The Linux distribution used (``hostnamectl | grep 'Operating System'``) =20 - * the output from ``cat /proc/version``, which contains the Linux kernel - version number and the compiler it was built with. +* The nature of the issue and when it occurs. =20 - * the Linux distribution the machine is running (``hostnamectl | grep - "Operating System"``) +* If you are dealing with a regression and performed a bisection, mention + The author, subject, and commit-id of the culprit change. =20 - * the architecture of the CPU and the operating system (``uname -mi``) +* If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the ker= nel, + include it. If you can't copy and paste it, take a picture of the screen. =20 - * if you are dealing with a regression and performed a bisection, mention= the - subject and the commit-id of the change that is causing it. =20 -Things that might be wise to provide +Things that might be good to provide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Depending on the issue you might need to add more background data. Here ar= e a -few suggestions what often is good to provide: - - * If the issue might be related to your computer hardware, mention what k= ind - of system you use. If you for example have problems with your graphics = card, - mention its manufacturer, the card's model, and what chip is uses. If i= t's a - laptop mention its name, but try to make sure it's meaningful. 'Dell XP= S 13' - for example is not, because it might be the one from 2012; that one loo= ks - not that different from the one sold today, but apart from that the two= have - nothing in common. Hence, in such cases add the exact model number, whi= ch - for example are '9380' or '7390' for XPS 13 models introduced during 20= 19. - Names like 'Lenovo Thinkpad T590' are also somewhat ambiguous: there are - variants of this laptop with and without a dedicated graphics chip, so = try - to find the exact model name or specify the main components. - - * Mention the relevant software in use. If you have problems with loading - modules, you want to mention the versions of kmod, systemd, and udev in= use. - If one of the DRM drivers misbehaves, you want to state the versions of - libdrm and Mesa; also specify your Wayland compositor or the X-Server a= nd - its driver. If you have a filesystem issue, mention the version of - corresponding filesystem utilities (e2fsprogs, btrfs-progs, xfsprogs, .= ..). - -Those examples should give your some ideas of what data might be wise to -attach, but you have to think yourself what will be helpful for others to = know. +In some cases it is wise to provide additional details: + +* The processor architecture used (``uname -mi``). + +* The relevant software in use. If you have problems with loading + modules, you want to mention the versions of kmod, systemd, and udev in = use. + If one of the DRM drivers misbehaves, you want to state the versions of + libdrm and Mesa; also specify your Wayland compositor or the X-Server and + its driver. + +* If the issue might be related to your hardware, mention what kind + of system you use. If you, for example, have problems with your graphics= card, + mention its manufacturer, the card's model, and what chip it uses. If it= is a + laptop, specify its name, but try to make sure it is meaningful. 'Dell X= PS + 13', for example, is not, because that might be the one from 2012 or 202= 0; + the latter might not look that different, but apart from that it shares + nothing with the former. In such cases add the exact model number, like = '9380' + or '7390' for XPS 13 models introduced during 2019. Names like 'Lenovo + Thinkpad T590' are also somewhat ambiguous: There are variants of this l= aptop + with and without a dedicated graphics chip, so try to find the exact mod= el + name or specify the main components. + +Those examples should give you some ideas of what data might be wise to +specify, but you have to think through yourself what will be helpful for o= thers +to know. + Don't worry too much about forgetting something, as developers will ask for additional details they need. But making everything important available fr= om the start increases the chance someone will take a closer look. =20 +Special handling for high-priority issues +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -The important part: the head of your report -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Reports for high-priority issues need special handling: =20 -Now that you have the detailed part of the report prepared let's get to the -most important section: the first few sentences. Thus go to the top, add -something like 'The detailed description:' before the part you just wrote = and -insert two newlines at the top. Now write one normal length paragraph that -describes the issue roughly. Leave out all boring details and focus on the -crucial parts readers need to know to understand what this is all about; i= f you -think this bug affects a lot of users, mention this to get people interest= ed. +* Regressions: Make the report's subject start with '[REGRESSION]'. =20 -Once you did that insert two more lines at the top and write a one sentence -summary that explains quickly what the report is about. After that you hav= e to -get even more abstract and write an even shorter subject/title for the rep= ort. + In case you performed a successful bisection, use the title of the chang= e that + introduced the regression as the second part of your subject. Make the r= eport + also mention the commit-id of the culprit. In case of an unsuccessful + bisection, make your report mention the latest tested version that is wo= rking + fine (say 5.7) and the oldest where the issue occurs (say 5.8-rc1). =20 -Now that you have written this part take some time to optimize it, as it i= s the -most important parts of your report: a lot of people will only read this b= efore -they decide if reading the rest is time well spent. + When sending the report by email, CC the Linux regressions mailing list + (regressions@lists.linux.dev). In case the report needs to be filed to s= ome + web tracker, proceed to do so. Once filed, forward the report by email t= o the + regressions list; CC the maintainer and the mailing list for the subsyst= em in + question. Make sure to inline the forwarded report and do not attach it. + Also add a short note at the top where you mention the URL to the ticket. =20 -Now send or file the report like the :ref:`MAINTAINERS ` file= told -you, unless it's one of those 'issues of high priority' outlined earlier: = in -that case please read the next subsection first before sending the report = on -its way. + When mailing or forwarding the report, in case of a successful bisection= , add + the author of the culprit to the recipients; also CC everyone in the + signed-off-by chain, which you find at the end of its commit message. =20 -Special handling for high priority issues -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Security issues: For these issues you will have to evaluate if a + short-term risk to other users would arise if details were publicly disc= losed. + If that is not the case, simply proceed with reporting the issue as desc= ribed. + For issues that bear such a risk, you will need to adjust the reporting + process slightly: =20 -Reports for high priority issues need special handling. + * If the MAINTAINERS file instructed you to report the issue by email, d= o not + CC any public mailing lists. =20 -**Severe issues**: make sure the subject or ticket title as well as the fi= rst -paragraph makes the severeness obvious. + * If you were supposed to file the issue in a bug tracker, make sure to = mark + the ticket as 'private' or 'security issue'. If the bug tracker does n= ot + offer a way to keep reports private, forget about it and send your rep= ort as + a private email to the maintainers instead. =20 -**Regressions**: make the report's subject start with '[REGRESSION]'. + In both cases, make sure to also email your report to the addresses the + MAINTAINERS file lists in the section 'security contact'. Ideally, direct= ly CC + them when sending the report by email. If you filed it in a bug tracker, = forward + the report's text to these addresses; but on top of it, put a small note = where + you mention that you filed it with a link to the ticket. =20 -In case you performed a successful bisection, use the title of the change = that -introduced the regression as the second part of your subject. Make the rep= ort -also mention the commit id of the culprit. In case of an unsuccessful bise= ction, -make your report mention the latest tested version that's working fine (sa= y 5.7) -and the oldest where the issue occurs (say 5.8-rc1). + See Documentation/process/security-bugs.rst for more information. =20 -When sending the report by mail, CC the Linux regressions mailing list -(regressions@lists.linux.dev). In case the report needs to be filed to som= e web -tracker, proceed to do so. Once filed, forward the report by mail to the -regressions list; CC the maintainer and the mailing list for the subsystem= in -question. Make sure to inline the forwarded report, hence do not attach it. -Also add a short note at the top where you mention the URL to the ticket. +Optimize the report and especially its head section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -When mailing or forwarding the report, in case of a successful bisection a= dd the -author of the culprit to the recipients; also CC everyone in the signed-of= f-by -chain, which you find at the end of its commit message. +Once you have everything covered in your report, it is wise to optimize the +most important section: The first few sentences. =20 -**Security issues**: for these issues your will have to evaluate if a -short-term risk to other users would arise if details were publicly disclo= sed. -If that's not the case simply proceed with reporting the issue as describe= d. -For issues that bear such a risk you will need to adjust the reporting pro= cess -slightly: +If the report is long, it is usually a good idea to go to the top, add +something like 'The detailed description:' before the part you just wrote,= and +insert two newlines at the top. Now write one normal length paragraph that +describes the issue roughly. Leave out all boring details and focus on the +crucial parts readers need to know to understand what this is all about. + +Whenever you have or do not have such a paragraph with a gist, ideally sta= rt the +report with one sentence that explains quickly what the report is about. + +Now try to write an even shorter subject/title for the report. =20 - * If the MAINTAINERS file instructed you to report the issue by mail, do = not - CC any public mailing lists. +Spending time on these things is time well spent, as a lot of people will = only +read the subject and maybe the first sentence or two before they decide if +reading the rest is worth it for them. + +Now send or file the report like the :ref:`MAINTAINERS ` file= told +you, unless it is one of those 'issues of high-priority' outlined earlier:= In +that case, please read the next subsection first before sending the report= on +its way. + +[:ref:`back to step-by-step guide `] + + +.. _submit_repiref: + +Submit the report +----------------- =20 - * If you were supposed to file the issue in a bug tracker make sure to ma= rk - the ticket as 'private' or 'security issue'. If the bug tracker does not - offer a way to keep reports private, forget about it and send your repo= rt as - a private mail to the maintainers instead. + *Submit your report in the appropriate way, which depends on the outcome= * [:ref:`... `] =20 -In both cases make sure to also mail your report to the addresses the -MAINTAINERS file lists in the section 'security contact'. Ideally directly= CC -them when sending the report by mail. If you filed it in a bug tracker, fo= rward -the report's text to these addresses; but on top of it put a small note wh= ere -you mention that you filed it with a link to the ticket. +The step-by-step guide covers all the important details already. =20 -See Documentation/process/security-bugs.rst for more information. +[:ref:`back to step-by-step guide `] =20 =20 Duties after the report went out --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 23EBD2DE6E3; Sun, 26 Oct 2025 12:42:34 +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=1761482558; cv=none; b=ZdQC2O4MK/2VCxFbP36L2IqLZ11DNnAftxlJ9fum7kWgPXI2GqdoVh0DJKvVCMm42l2TZIFhctC44ZLHt/kyNi1gFqL9uihJ8t2LSv3KrLCDWR9vDJOHeAO97BUBrofexCG2XMBrpCUkWjwRM8qEDDltas2sHiyRRHrH/7eJjfo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482558; c=relaxed/simple; bh=rNZIoC6pDpscutI+1aAPe3z6yjg/MlPZ7XDTm/LQhsM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=rsnDrwzXqnnLz8R1iYdLfbMWe4CiAtOuQQmaC/J4cg3MHxdVsZ8Tmc0o7NYWLNihOX+SHO+OfsW6qZSV6hjkvjH7cEGO3fqD1YlcxkihhLHTXiDIi+i2iWx59ck1zzsO9P3+efKASBCXYVQoynUv/NLjQnohzhcdFnbuOjPyQhg= 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=FQZ4C1j4; 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="FQZ4C1j4" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=leemhuis.info; s=he214686; h=Content-Transfer-Encoding:Content-Type: 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=K7qoI4NF+hR2zU8RlYf5/2Ju3tpWLz9BGYsIERml1u8=; t=1761482555; x=1761914555; b=FQZ4C1j4YrS/vJORr4XB06Pv7fNh3TBAwbekJSPHgile9OG1S7ouVVuA/ySX1 bAt2Cyfb828/2ZEwqrJen82hr39B1D5qXoVoY6dQIgYCYPwmr1ew+8mazds/aTTsgEs05bowL2XRC wkg3FRthOUTvBwUovabvxw5eNIrSuM0/H35wZV8/L8gIPUYpashzSNVMhddWswwjsixUOXac4FVbs BvpqwzGb0DkM4BIKWCTzbCk23FLFtBI4vfmiSxupATHS+6g5FHjEOOpHEqm2hWjOarCnf2Lq49bEu O81ikzqxJ0bVVa0tD7h4YzAPRXyeDVfymhBTl/JxYrSDqhvPDw==; 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 1vD04v-001mZC-16; Sun, 26 Oct 2025 13:42:33 +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 29/30] docs: reporting-issues: separate steps for follow-up tasks Date: Sun, 26 Oct 2025 13:42:20 +0100 Message-ID: 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-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1761482555;32bd3f7a; X-HE-SMSGID: 1vD04v-001mZC-16 Create three separate steps that cover things that are important for bug reporters to keep an eye on after submitting the report. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 347 +++++++++--------- 1 file changed, 175 insertions(+), 172 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index c147191a7d0987..d81d558c245953 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -372,12 +372,41 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 - * Wait for reactions and keep the thing rolling until you can accept the - outcome in one way or the other. Thus react publicly and in a timely ma= nner - to any inquiries. Test proposed fixes. Do proactive testing: retest wit= h at - least every first release candidate (RC) of a new mainline version and - report your results. Send friendly reminders if things stall. And try to - help yourself, if you don't get any help or if it's unsatisfying. +.. _keeprolling_repisbs: + +* Wait for reactions and keep the ball rolling until you can accept the ou= tcome + in one way or the other. Hence react publicly and in a timely manner to = any + inquiries and requests for testing patches. + + [:ref:`details `] + +.. _retest_repisbs: + +* Retest at least every first release candidate (e.g., -rc1) of a new main= line + version released and report your findings in a reply to your report. + + [:ref:`details `] + +.. _reminder_repisbs: + +* If things stall for more than three weeks, evaluate why. It can happen d= ue to + good or bad reasons -- like an inadequate report or because you + missed a request for further details or testing. If it is unlikely to be + something like that, send a friendly inquiry as a reply-to-self, as it m= ight + be a mundane reason like an over-eager spam filter or a developer being = on + vacation. + + [:ref:`details `] + +.. _yourself_repisbs: + +* Be aware that nobody is obliged to help you, unless it is a recent regre= ssion, + a security issue, or an extremely severe problem. Hence, try to help you= rself + if you don't receive any or only unsatisfying help. + + [:ref:`details `] + +.. _readysolved_repisubs: =20 =20 Handling non-regressions only occurring in stable or longterm kernels @@ -1327,193 +1356,167 @@ The step-by-step guide covers all the important d= etails already. [:ref:`back to step-by-step guide `] =20 =20 -Duties after the report went out --------------------------------- +.. _keeprolling_repiref: + +Things to do after the report went out +-------------------------------------- =20 - *Wait for reactions and keep the thing rolling until you can accept the - outcome in one way or the other. Thus react publicly and in a timely m= anner - to any inquiries. Test proposed fixes. Do proactive testing: retest wi= th at - least every first release candidate (RC) of a new mainline version and - report your results. Send friendly reminders if things stall. And try = to - help yourself, if you don't get any help or if it's unsatisfying.* + *Wait for reactions and keep the ball rolling until you can accept the o= utcome* [:ref:`... `] =20 -If your report was good and you are really lucky then one of the developers -might immediately spot what's causing the issue; they then might write a p= atch -to fix it, test it, and send it straight for integration in mainline while -tagging it for later backport to stable and longterm kernels that need it.= Then -all you need to do is reply with a 'Thank you very much' and switch to a v= ersion -with the fix once it gets released. +If your report was good and you are lucky, some developers might immediate= ly +spot what is causing the issue. They then might provide a fix for you to t= est, +which you should do in a timely manner; afterwards they then send it out f= or +integration into the mainline kernel while tagging it for backporting to +affected stable and longterm kernels if appropriate. =20 -But this ideal scenario rarely happens. That's why the job is only starting -once you got the report out. What you'll have to do depends on the situati= ons, -but often it will be the things listed below. But before digging into the -details, here are a few important things you need to keep in mind for this= part -of the process. +But frequently it is a little less straightforward. That is why the job of= ten +is only starting once you send a report. What you'll have to do depends on= the +situation. Here are a few tips: =20 +**Check who you deal with**: Most of the time a +developer for the particular area of code will respond. But as +issues are usually reported in public, it could be anyone -- +including people that want to help but in the end send you off +track. That is why it might be wise to run a quick search on `lore `_ +to see who you are interacting with. =20 -General advice for further interactions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Inquiries for data**: Often you will be asked to test something or provi= de +additional details. Try to supply the requested information soon, as you h= ave +the attention of someone willing to help and risk losing it the longer you +wait; that outcome is even likely if you do not provide the information wi= thin +a few business days. =20 -**Always reply in public**: When you filed the issue in a bug tracker, alw= ays -reply there and do not contact any of the developers privately about it. F= or -mailed reports always use the 'Reply-all' function when replying to any ma= ils -you receive. That includes mails with any additional data you might want t= o add -to your report: go to your mail applications 'Sent' folder and use 'reply-= all' -on your mail with the report. This approach will make sure the public mail= ing -list(s) and everyone else that gets involved over time stays in the loop; = it -also keeps the mail thread intact, which among others is really important = for -mailing lists to group all related mails together. +**Always reply in public!** When you submitted the issue in a bug tracker, +always reply there and do not contact any of the developers privately; for +mailed reports, always use the 'Reply-all' function when replying to any e= mails +you receive. That includes emails with any additional data you might want = to add +to your report: Go to your email application's 'Sent' folder and use 'repl= y-all' +on your email with the report. This approach will make sure the public mai= ling +lists and everyone else who becomes involved later can access everything; = it +also keeps the email thread intact, which, among others, is really importa= nt for +others that later run into the same problem and check the thread for a sol= ution. =20 There are just two situations where a comment in a bug tracker or a 'Reply= -all' is unsuitable: =20 - * Someone tells you to send something privately. +* Someone tells you to send something privately. + +* You were told to supply something containing + information that should not be exposed to the public. In that case, it i= s okay + to send it in private to the person who asked for it. But note in the ti= cket + or an email that you did so to keep the public record straight. =20 - * You were told to send something, but noticed it contains sensitive - information that needs to be kept private. In that case it's okay to se= nd it - in private to the developer that asked for it. But note in the ticket o= r a - mail that you did that, so everyone else knows you honored the request. +**Requests for testing**: When you are asked to test a diagnostic patch or= a +possible fix, try to test it in a timely manner, too. But do it thoroughly= and +do not rush it: Mixing things up can happen easily and leads to a lot of +confusion. A common mistake, for example, is thinking a proposed fix was a= pplied +when building a test kernel, when in fact it was not. =20 -**Do research before asking for clarifications or help**: In this part of = the +**Try to help yourself** before asking for help: During this part of the process someone might tell you to do something that requires a skill you m= ight not have mastered yet. For example, you might be asked to use some test to= ols -you never have heard of yet; or you might be asked to apply a patch to the -Linux kernel sources to test if it helps. In some cases it will be fine se= nding -a reply asking for instructions how to do that. But before going that rout= e try -to find the answer own your own by searching the internet; alternatively -consider asking in other places for advice. For example ask a friend or po= st -about it to a chatroom or forum you normally hang out. - -**Be patient**: If you are really lucky you might get a reply to your repo= rt -within a few hours. But most of the time it will take longer, as maintaine= rs -are scattered around the globe and thus might be in a different time zone = =E2=80=93 one -where they already enjoy their night away from keyboard. - -In general, kernel developers will take one to five business days to respo= nd to -reports. Sometimes it will take longer, as they might be busy with the mer= ge -windows, other work, visiting developer conferences, or simply enjoying a = long -summer holiday. - -The 'issues of high priority' (see above for an explanation) are an except= ion -here: maintainers should address them as soon as possible; that's why you -should wait a week at maximum (or just two days if it's something urgent) -before sending a friendly reminder. - -Sometimes the maintainer might not be responding in a timely manner; other -times there might be disagreements, for example if an issue qualifies as -regression or not. In such cases raise your concerns on the mailing list a= nd -ask others for public or private replies how to move on. If that fails, it -might be appropriate to get a higher authority involved. In case of a WiFi -driver that would be the wireless maintainers; if there are no higher level -maintainers or all else fails, it might be one of those rare situations wh= ere -it's okay to get Linus Torvalds involved. - -**Proactive testing**: Every time the first pre-release (the 'rc1') of a n= ew -mainline kernel version gets released, go and check if the issue is fixed = there -or if anything of importance changed. Mention the outcome in the ticket or= in a -mail you sent as reply to your report (make sure it has all those in the CC -that up to that point participated in the discussion). This will show your -commitment and that you are willing to help. It also tells developers if t= he -issue persists and makes sure they do not forget about it. A few other -occasional retests (for example with rc3, rc5 and the final) are also a go= od -idea, but only report your results if something relevant changed or if you= are -writing something anyway. - -With all these general things off the table let's get into the details of = how -to help to get issues resolved once they were reported. - -Inquires and testing request -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Here are your duties in case you got replies to your report: - -**Check who you deal with**: Most of the time it will be the maintainer or= a -developer of the particular code area that will respond to your report. Bu= t as -issues are normally reported in public it could be anyone that's replying = =E2=80=94 -including people that want to help, but in the end might guide you totally= off -track with their questions or requests. That rarely happens, but it's one = of -many reasons why it's wise to quickly run an internet search to see who yo= u're -interacting with. By doing this you also get aware if your report was hear= d by -the right people, as a reminder to the maintainer (see below) might be in = order -later if discussion fades out without leading to a satisfying solution for= the -issue. +you have never heard of yet; or you are asked to apply a patch to the +Linux kernel sources to test. It usually will be fine replying asking for +instructions on how to do that. But before going that route, try to find t= he +answer on your own by searching the internet; alternatively, +consider asking elsewhere for advice. For example, ask a friend or post +your question to a chat room or forum you normally hang out in. =20 -**Inquiries for data**: Often you will be asked to test something or provi= de -additional details. Try to provide the requested information soon, as you = have -the attention of someone that might help and risk losing it the longer you -wait; that outcome is even likely if you do not provide the information wi= thin -a few business days. +**Be patient**: If you are really lucky, you might receive a reply to your +report within a few hours. But most of the time it will take longer, as +maintainers might be in a different time zone -- one where people currently +take a few days off or already enjoy their night away from the keyboard. T= hey +might also simply be busy with other work, on a trip to a conference, or s= imply +enjoying a long holiday. =20 -**Requests for testing**: When you are asked to test a diagnostic patch or= a -possible fix, try to test it in timely manner, too. But do it properly and= make -sure to not rush it: mixing things up can happen easily and can lead to a = lot -of confusion for everyone involved. A common mistake for example is thinki= ng a -proposed patch with a fix was applied, but in fact wasn't. Things like that -happen even to experienced testers occasionally, but they most of the time= will -notice when the kernel with the fix behaves just as one without it. +[:ref:`back to step-by-step guide `] + + +.. _retest_repiref: + +Regularly check if the bug is still present +------------------------------------------- + + *Retest at least every first release candidate (e.g., -rc1) of a new mai= nline + version released and* [:ref:`... `] + +Every time the first pre-release of a new mainline kernel version is relea= sed +(the 'rc1'), go and check if the issue is fixed there or if anything of +importance has changed. Mention the outcome in the ticket or in a mailed r= eply +to your report (make sure to CCs everyone that up to that point participat= ed in +the discussion). This will show your commitment. It also tells developers = the +issue persists and acts as an implicit reminder. + +An occasional retest at another time (for example, with -rc4 or -rc7) is a= lso +wise, but only report your results if something relevant changed or if you= are +writing anyway. + +[:ref:`back to step-by-step guide `] + + +.. _reminder_repiref: =20 What to do when nothing of substance happens -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some reports will not get any reaction from the responsible Linux kernel -developers; or a discussion around the issue evolved, but faded out with -nothing of substance coming out of it. - -In these cases wait two (better: three) weeks before sending a friendly -reminder: maybe the maintainer was just away from keyboard for a while when -your report arrived or had something more important to take care of. When -writing the reminder, kindly ask if anything else from your side is needed= to -get the ball running somehow. If the report got out by mail, do that in the -first lines of a mail that is a reply to your initial mail (see above) whi= ch -includes a full quote of the original report below: that's on of those few -situations where such a 'TOFU' (Text Over, Fullquote Under) is the right -approach, as then all the recipients will have the details at hand immedia= tely -in the proper order. - -After the reminder wait three more weeks for replies. If you still don't g= et a -proper reaction, you first should reconsider your approach. Did you maybe = try -to reach out to the wrong people? Was the report maybe offensive or so -confusing that people decided to completely stay away from it? The best wa= y to -rule out such factors: show the report to one or two people familiar with = FLOSS -issue reporting and ask for their opinion. Also ask them for their advice = how -to move forward. That might mean: prepare a better report and make those p= eople -review it before you send it out. Such an approach is totally fine; just +-------------------------------------------- + + *If things stall for more than two to three weeks, evaluate why. It can + happen due to good or bad reasons, like* [:ref:`... `] + +Sometimes you will not receive any reaction from the responsible +developers; or a discussion around the issue evolves but ends fruitlessly. + +In these cases, wait two to three weeks before sending a friendly +reminder: Maybe the right developers were just away from their keyboards w= hen +you sent your report or had something more important to take care of. + +When writing the reminder, kindly ask if there was anything wrong with the +report or if anything from your side is needed to get the ball rolling. If= the +report was submitted by email, send a reply inserting your query after quo= ting +the intro while including a full quote of the original report below: Then = all +the recipients will have both the gist of the problem and the details at h= and +immediately in convenient order. + +After sending a reminder, wait three more weeks for replies. If you still = don't +receive a proper reaction, reconsider your approach. Did you maybe try +to reach out to the wrong people? Was the report possibly offensive or so +confusing that people decided to stay away from it? + +The best way to +rule out such factors: Show the report to one or two people familiar with = FLOSS +issue reporting and ask for their opinion. Also ask them for their advice = on how +to move forward. That might mean preparing a better report and making those +people review it before sending it out. Such an approach is totally fine; = just mention that this is the second and improved report on the issue and inclu= de a link to the first report. =20 -If the report was proper you can send a second reminder; in it ask for adv= ice -why the report did not get any replies. A good moment for this second remi= nder -mail is shortly after the first pre-release (the 'rc1') of a new Linux ker= nel -version got published, as you should retest and provide a status update at= that -point anyway (see above). - -If the second reminder again results in no reaction within a week, try to -contact a higher-level maintainer asking for advice: even busy maintainers= by -then should at least have sent some kind of acknowledgment. - -Remember to prepare yourself for a disappointment: maintainers ideally sho= uld -react somehow to every issue report, but they are only obliged to fix those -'issues of high priority' outlined earlier. So don't be too devastating if= you -get a reply along the lines of 'thanks for the report, I have more importa= nt -issues to deal with currently and won't have time to look into this for the -foreseeable future'. - -It's also possible that after some discussion in the bug tracker or on a l= ist -nothing happens anymore and reminders don't help to motivate anyone to wor= k out -a fix. Such situations can be devastating, but is within the cards when it -comes to Linux kernel development. This and several other reasons for not -getting help are explained in 'Why some issues won't get any reaction or r= emain -unfixed after being reported' near the end of this document. - -Don't get devastated if you don't find any help or if the issue in the end= does -not get solved: the Linux kernel is FLOSS and thus you can still help your= self. -You for example could try to find others that are affected and team up with -them to get the issue resolved. Such a team could prepare a fresh report -together that mentions how many you are and why this is something that in = your -option should get fixed. Maybe together you can also narrow down the root = cause -or the change that introduced a regression, which often makes developing a= fix -easier. And with a bit of luck there might be someone in the team that kno= ws a -bit about programming and might be able to write a fix. +If the report was proper, you can send a second reminder; in it, ask for a= dvice +on why the report did not receive any replies. An ideal moment for this is +shortly after retesting with the first pre-release of a new mainline relea= se +(the 'rc1'), as you should retest and provide a status update at that point +anyway (see above). + +[:ref:`back to step-by-step guide `] + + +.. _yourself_repiref: + +In most cases nobody is obliged to help +--------------------------------------- + +*Be aware that nobody is obliged to help you, unless it is* [:ref:`... `] + +Developers ideally should react somehow to every issue report, but sometim= es do +not reply or, in the end, do not address problems. This is due to reasons +[:ref:`Why some bugs remain unfixed and some reports are ignored `] +explains in more detail, which also explains why some code does not even h= ave +maintainers. + +Try to help yourself in that case. +You, for example, could team up with others affected to then create a bett= er +report or narrow down the root cause of a problem. With a bit of luck, som= eone +on the team might even know a bit about programming and provide a fix. + +[:ref:`back to step-by-step guide `] =20 =20 Appendix: additional background information --=20 2.51.0 From nobody Sun Feb 8 13:08:52 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 019852DECA5; Sun, 26 Oct 2025 12:42:35 +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=1761482559; cv=none; b=KMEu22S+hxWyIfn0gyz/6nUacr8hYMfQXoZPrAYVjFmifO9UINpKVrREdRk6jqNnTjTpUavuLe62Z0WYJQcLKMJHK7B3+knrE+aUufho0BYZrfIP5sSRwc+MqXcYZymhJHXK+p4NhjuzEFTelwP3dQJOJQGmJ47zYW63hiwG+3w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482559; c=relaxed/simple; bh=h6SqvcvUog3ZeKTv5PDcD6B9tSNUV8nC3QKFWkF9PX8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=MA6T1Z5CPW+U90Bx7zFblfFDw44gGeKU+m5O/26/53iUYs2rv5TOi8w99b8ntCwv36AfeeS8hVNfJr4lrDBuV+eJP7gHnUEJ59C4nJYJN//OxBWfL56ShhyUYFQPk2pZoLa0V6mZ328YbeHX1zAImA1BBSm/o1zmWJIPu/uHav0= 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=Ag8GKHQh; 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="Ag8GKHQh" 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=x532wENFbOyhena6xhVRGm7cbvhCcWeQykKTHgTZZA8=; t=1761482556; x=1761914556; b=Ag8GKHQhSsXBddRbFCuKUchSUyu3ORipw1nVqw4GDS/0e3cjgp827vfRkmk1v Vb4rKCD3tAbnqg9CS9+Rk+nNuMnRNx2FKcki/ax4g8IovZMkuZD1BLOqfSlGGBMMZjvab0+YmrkrI LZjozfG412Ixh6sllE+oQlsI0oRP6pTC/9oSIwNOfyOvcQgc+mVHKz2+C7TslsVepqCu1V/lfDu43 ovLuOlBCuHf/i8SE99XzPNz5YpQ+b453pOJInPYlGQUnrs1ZwdMNGdOBQtODs+P4TqTKSUDMhDLxZ /KBBuB5b8oBCpDO9ZZtbKsdW+nf7LkKEH+6Rqb58FzM9UYliew==; 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 1vD04v-001mZc-31; Sun, 26 Oct 2025 13:42:34 +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 30/30] docs: reporting-issues: fix a few line breaks Date: Sun, 26 Oct 2025 13:42:21 +0100 Message-ID: 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;1761482556;46d92887; X-HE-SMSGID: 1vD04v-001mZc-31 Content-Type: text/plain; charset="utf-8" Rewrap a few paragraphs that have odd line breaks to keep the diff clearer in preceding changes. Apart from that no text changes. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 230 +++++++++--------- 1 file changed, 111 insertions(+), 119 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index d81d558c245953..3b1519fe80511f 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -615,29 +615,29 @@ Check 'taint' flag *Check if the kernel was already 'tainted' when the issue first occurred= * [:ref:`... `] =20 The kernel marks itself with a 'taint' flag when something happens that mi= ght -lead to follow-up errors looking totally unrelated. Your issue might -be such an error, in which case there is nothing to report. That is why it= is -in your interest to check the taint status early in the reporting process.= This -is the main reason why this step is here in the guide, as you most likely = will -have to install a different kernel for reporting later -- and then need to -recheck the flag, as that is when it matters. +lead to follow-up errors looking totally unrelated. Your issue might be su= ch an +error, in which case there is nothing to report. That is why it is in your +interest to check the taint status early in the reporting process. This is= the +main reason why this step is here in the guide, as you most likely will ha= ve to +install a different kernel for reporting later -- and then need to recheck= the +flag, as that is when it matters. =20 To check the tainted flag, execute ``cat /proc/sys/kernel/tainted``: If it returns '0' everything is fine; if it contains a higher number, it is tain= ted. =20 -In some situations it is impossible to check that file. That is -why the kernel also mentions the taint status when it reports small (a -'warning' or a 'bug') or big (an 'Oops' or a 'panic') problems. In such ca= ses, -search for a line starting with 'CPU:' near the top of the error messages -printed on the screen or in the log. If the kernel at that point considered -itself to be fine, it will end with 'Not tainted'; if not, you will see -'Tainted:' followed by a few spaces and some letters. +In some situations it is impossible to check that file. That is why the ke= rnel +also mentions the taint status when it reports small (a 'warning' or a 'bu= g') or +big (an 'Oops' or a 'panic') problems. In such cases, search for a line st= arting +with 'CPU:' near the top of the error messages printed on the screen or in= the +log. If the kernel at that point considered itself to be fine, it will end= with +'Not tainted'; if not, you will see 'Tainted:' followed by a few spaces an= d some +letters. =20 If your kernel is tainted, check Documentation/admin-guide/tainted-kernels= .rst -to find out why. Note: It is quite possible that the problem you ran into -caused the kernel to taint itself, in which case you are free to ignore the -flag. But if the kernel was tainted beforehand, you might have to eliminat= e the -cause or rule out that it is an influence. +to find out why. Note: It is quite possible that the problem you ran into = caused +the kernel to taint itself, in which case you are free to ignore the flag.= But +if the kernel was tainted beforehand, you might have to eliminate the caus= e or +rule out that it is an influence. =20 These are the most frequent reasons why the kernel set the flag: =20 @@ -649,18 +649,17 @@ These are the most frequent reasons why the kernel se= t the flag: Oops: 0000 [#1] SMP =20 That is the first Oops since boot-up, as the '#1' between the brackets = shows. - Every later Oops and any other problem that happens afterwards might be - a follow-up issue - that would never have happened otherwise, even if both look totally unr= elated. - Rule this out by eliminating the cause for the first Oops and reproduci= ng - the issue afterwards. Sometimes simply restarting will be enough; other= times - a change to the configuration followed by a reboot can eliminate the Oo= ps. + Every later Oops and any other problem that happens afterwards might be= a + follow-up issue that would never have happened otherwise, even if both = look + totally unrelated. Rule this out by eliminating the cause for the firs= t Oops + and reproducing the issue afterwards. Sometimes simply restarting will = be + enough; other times a change to the configuration followed by a reboot = can + eliminate the Oops. =20 Note: Do not invest too much time into this while you are still on an - outdated or vendor kernel: The cause for the Oops might already be fixe= d in - a newer Linux kernel - version you most likely will have to install for reporting while follow= ing - this guide. + outdated or vendor kernel: The cause for the Oops might already be fixe= d in a + newer Linux kernel version you most likely will have to install for rep= orting + while following this guide. =20 2. Your system uses software that installs externally developed kernel mod= ules, for example, kernel modules from Nvidia, OpenZFS, VirtualBox, or VMware= . The @@ -838,10 +837,9 @@ development process: * You deal with a regression, if some application or practical use case ru= nning fine with one Linux kernel version works worse or not at all with a newer version compiled using a similar configuration; the 'no regression' rule - forbids that. The document - Documentation/admin-guide/reporting-regressions.rst explains these and - additional aspects in more detail, but everything important is covered in - this document. + forbids that. The document Documentation/admin-guide/reporting-regressio= ns.rst + explains these and additional aspects in more detail, but everything imp= ortant + is covered in this document. =20 * What qualifies as a security issue is left to your judgment. Consider re= ading Documentation/process/security-bugs.rst before proceeding, which @@ -892,12 +890,10 @@ How to read the MAINTAINERS file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 To illustrate how to use the :ref:`MAINTAINERS ` file, let's = assume -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. +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 developers will involve the right peop= le. =20 Sadly, there is no way to check which code is driving a particular hardware component that is both universal and easy. @@ -953,9 +949,8 @@ only has someone who provides 'Odd Fixes' when feeling = motivated. And with 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:' ('B:'): 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:'): I= t 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 email: Very few subsystem= s use a bug tracker, and only some of those rely on bugzilla.kernel.org. @@ -1158,9 +1153,9 @@ addresses that allow pinpointing the exact path to th= e line in your kernel's source code that triggered the issue. Many bugs can be resolved without decoding these addresses, but for some it is helpful or required. =20 -That is why it is fine to report problems without bothering about this, but -when asked for this, try to decode the stack trace. Note: This requires a -kernel build with CONFIG_DEBUG_INFO and CONFIG_KALLSYMS enabled. +That is why it is fine to report problems without bothering about this, bu= t when +asked for this, try to decode the stack trace. Note: This requires a kernel +build with CONFIG_DEBUG_INFO and CONFIG_KALLSYMS enabled. =20 Usually you want to decode using a script shipped in the Linux sources. If= you are running a kernel you compiled yourself, call it like this:: @@ -1187,10 +1182,10 @@ In this case the executed code was built from the f= ile '~/linux-5.10.5/test-module/test-module.c' and the error occurred during t= he instructions found in line '16'. =20 -The script will similarly decode the addresses mentioned in the section -starting with 'Call trace', which shows the path to the function where the -problem occurred. The script, furthermore, will show the assembler output = for -the code section the kernel was executing at that time. +The script will similarly decode the addresses mentioned in the section st= arting +with 'Call trace', which shows the path to the function where the problem +occurred. The script, furthermore, will show the assembler output for the = code +section the kernel was executing at that time. =20 [:ref:`back to step-by-step guide `] =20 @@ -1202,10 +1197,10 @@ Prepare and optimize the report =20 *Prepare and optimize the report.* [:ref:`... `] =20 -Most developers just take a few seconds to skim a report before deciding -between taking a closer look or moving on, as they receive a ton of messag= es. -That is why the title/subject, the first sentence, and the three or four -following it are crucial. +Most developers just take a few seconds to skim a report before deciding b= etween +taking a closer look or moving on, as they receive a ton of messages. Tha= t is +why the title/subject, the first sentence, and the three or four following= it +are crucial. =20 People will also stop reading if the report's text is long or hard to foll= ow; the same is true if crucial information is not at hand. So be sure to desc= ribe @@ -1373,12 +1368,11 @@ But frequently it is a little less straightforward.= That is why the job often is only starting once you send a report. What you'll have to do depends on= the situation. Here are a few tips: =20 -**Check who you deal with**: Most of the time a -developer for the particular area of code will respond. But as -issues are usually reported in public, it could be anyone -- -including people that want to help but in the end send you off -track. That is why it might be wise to run a quick search on `lore `_ -to see who you are interacting with. +**Check who you deal with**: Most of the time a developer for the particul= ar +area of code will respond. But as issues are usually reported in public, it +could be anyone -- including people that want to help but in the end send = you +off track. That is why it might be wise to run a quick search on `lore +`_ to see who you are interacting with. =20 **Inquiries for data**: Often you will be asked to test something or provi= de additional details. Try to supply the requested information soon, as you h= ave @@ -1412,21 +1406,21 @@ do not rush it: Mixing things up can happen easily = and leads to a lot of confusion. A common mistake, for example, is thinking a proposed fix was a= pplied when building a test kernel, when in fact it was not. =20 -**Try to help yourself** before asking for help: During this part of the -process someone might tell you to do something that requires a skill you m= ight -not have mastered yet. For example, you might be asked to use some test to= ols -you have never heard of yet; or you are asked to apply a patch to the -Linux kernel sources to test. It usually will be fine replying asking for -instructions on how to do that. But before going that route, try to find t= he -answer on your own by searching the internet; alternatively, -consider asking elsewhere for advice. For example, ask a friend or post -your question to a chat room or forum you normally hang out in. +**Try to help yourself** before asking for help: During this part of the p= rocess +someone might tell you to do something that requires a skill you might not= have +mastered yet. For example, you might be asked to use some test tools you h= ave +never heard of yet; or you are asked to apply a patch to the Linux kernel +sources to test. It usually will be fine replying asking for instructions = on how +to do that. But before going that route, try to find the answer on your ow= n by +searching the internet; alternatively, consider asking elsewhere for advic= e. For +example, ask a friend or post your question to a chat room or forum you no= rmally +hang out in. =20 **Be patient**: If you are really lucky, you might receive a reply to your report within a few hours. But most of the time it will take longer, as -maintainers might be in a different time zone -- one where people currently -take a few days off or already enjoy their night away from the keyboard. T= hey -might also simply be busy with other work, on a trip to a conference, or s= imply +maintainers might be in a different time zone -- one where people currentl= y take +a few days off or already enjoy their night away from the keyboard. They m= ight +also simply be busy with other work, on a trip to a conference, or simply enjoying a long holiday. =20 [:ref:`back to step-by-step guide `] @@ -1462,12 +1456,12 @@ What to do when nothing of substance happens *If things stall for more than two to three weeks, evaluate why. It can happen due to good or bad reasons, like* [:ref:`... `] =20 -Sometimes you will not receive any reaction from the responsible -developers; or a discussion around the issue evolves but ends fruitlessly. +Sometimes you will not receive any reaction from the responsible developer= s; or +a discussion around the issue evolves but ends fruitlessly. =20 -In these cases, wait two to three weeks before sending a friendly -reminder: Maybe the right developers were just away from their keyboards w= hen -you sent your report or had something more important to take care of. +In these cases, wait two to three weeks before sending a friendly reminder: +Maybe the right developers were just away from their keyboards when you se= nt +your report or had something more important to take care of. =20 When writing the reminder, kindly ask if there was anything wrong with the report or if anything from your side is needed to get the ball rolling. If= the @@ -1477,17 +1471,16 @@ the recipients will have both the gist of the probl= em and the details at hand immediately in convenient order. =20 After sending a reminder, wait three more weeks for replies. If you still = don't -receive a proper reaction, reconsider your approach. Did you maybe try -to reach out to the wrong people? Was the report possibly offensive or so -confusing that people decided to stay away from it? - -The best way to -rule out such factors: Show the report to one or two people familiar with = FLOSS -issue reporting and ask for their opinion. Also ask them for their advice = on how -to move forward. That might mean preparing a better report and making those -people review it before sending it out. Such an approach is totally fine; = just -mention that this is the second and improved report on the issue and inclu= de a -link to the first report. +receive a proper reaction, reconsider your approach. Did you maybe try to = reach +out to the wrong people? Was the report possibly offensive or so confusing= that +people decided to stay away from it? + +The best way to rule out such factors: Show the report to one or two people +familiar with FLOSS issue reporting and ask for their opinion. Also ask th= em for +their advice on how to move forward. That might mean preparing a better re= port +and making those people review it before sending it out. Such an approach = is +totally fine; just mention that this is the second and improved report on = the +issue and include a link to the first report. =20 If the report was proper, you can send a second reminder; in it, ask for a= dvice on why the report did not receive any replies. An ideal moment for this is @@ -1507,14 +1500,14 @@ In most cases nobody is obliged to help =20 Developers ideally should react somehow to every issue report, but sometim= es do not reply or, in the end, do not address problems. This is due to reasons -[:ref:`Why some bugs remain unfixed and some reports are ignored `] -explains in more detail, which also explains why some code does not even h= ave -maintainers. +[:ref:`Why some bugs remain unfixed and some reports are ignored +`] explains in more detail, which also explains why = some +code does not even have maintainers. =20 -Try to help yourself in that case. -You, for example, could team up with others affected to then create a bett= er -report or narrow down the root cause of a problem. With a bit of luck, som= eone -on the team might even know a bit about programming and provide a fix. +Try to help yourself in that case. You, for example, could team up with o= thers +affected to then create a better report or narrow down the root cause of a +problem. With a bit of luck, someone on the team might even know a bit abo= ut +programming and provide a fix. =20 [:ref:`back to step-by-step guide `] =20 @@ -1548,35 +1541,34 @@ test. The former can happen when the publicly avail= able docs are superficial or when a driver was written with the help of reverse engineering. =20 Sooner or later, spare-time developers usually stop caring for the driver. -Maybe their test hardware broke, was replaced by something more fancy, or -became so old that it is something you don't find much outside of computer -museums anymore. Other times developers also stop caring when -something different in life becomes more important to them. Then sometimes -nobody is willing to take over the job as maintainer -- and nobody else ca= n be -forced to, as contributing is voluntary. The code nevertheless often stays -around, as it is useful for people; removing it would also cause a regress= ion, -which is not allowed in Linux. - -The situation is not that different with developers that are paid for their -work on the upstream Linux kernel. Those contribute the most changes these= days. -But their employers set the priorities. And those sooner or later stop car= ing -for some code or make their -employees focus on other things. Hardware vendors, for example, earn their= money -mainly by selling new hardware -- they thus often are not much interested = in -investing much time and energy in maintaining a Linux kernel driver for a = chip -they stopped selling years ago. Enterprise Linux distributors often care f= or a -longer time period, but in new versions might set support for old and rare -hardware aside to limit the scope, too. Often spare-time contributors take= over -once employed developers orphan some code, but as mentioned earlier: Soone= r or -later they will usually leave the code behind, too. - -Priorities are another reason why some issues are not fixed, as developers -quite often are forced to set those: The spare-time of volunteers or the t= ime +Maybe their test hardware broke, was replaced by something more fancy, or = became +so old that it is something you don't find much outside of computer museums +anymore. Other times developers also stop caring when something different = in +life becomes more important to them. Then sometimes nobody is willing to t= ake +over the job as maintainer -- and nobody else can be forced to, as contrib= uting +is voluntary. The code nevertheless often stays around, as it is useful for +people; removing it would also cause a regression, which is not allowed in +Linux. + +The situation is not that different with developers that are paid for thei= r work +on the upstream Linux kernel. Those contribute the most changes these days= . But +their employers set the priorities. And those sooner or later stop caring = for +some code or make their employees focus on other things. Hardware vendors,= for +example, earn their money mainly by selling new hardware -- they thus ofte= n are +not much interested in investing much time and energy in maintaining a Lin= ux +kernel driver for a chip they stopped selling years ago. Enterprise Linux +distributors often care for a longer time period, but in new versions migh= t set +support for old and rare hardware aside to limit the scope, too. Often +spare-time contributors take over once employed developers orphan some cod= e, but +as mentioned earlier: Sooner or later they will usually leave the code beh= ind, +too. + +Priorities are another reason why some issues are not fixed, as developers= quite +often are forced to set those: The spare-time of volunteers or the time employers allot for upstream Linux kernel work is often limited. Sometimes developers are also flooded with good and bad reports, even if a driver is -working well. To -not get completely stuck, the programmers might have no other choice than -to prioritize bug reports and ignore some. +working well. To not get completely stuck, the programmers might have no o= ther +choice than to prioritize bug reports and ignore some. =20 But do not worry too much about all of this, a lot of drivers have active maintainers who are quite interested in fixing as many issues as possible. --=20 2.51.0