mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Sasha Levin <sashal@kernel.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Sasha Levin <sashal@kernel.org>,
	Andrew Morton <akpm@linux-foundation.org>,
	Shuah Khan <skhan@linuxfoundation.org>,
	Randy Dunlap <rdunlap@infradead.org>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Theodore Ts'o <tytso@mit.edu>, Willy Tarreau <w@1wt.eu>,
	workflows@vger.kernel.org, linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: [PATCH] docs: submitting-patches: ask bug fixes for their user-visible impact
Date: Mon, 16 Nov 2026 14:14:36 -0500	[thread overview]
Message-ID: <20261116191436.188098-1-sashal@kernel.org> (raw)

"Describe your changes" already asks for the user-visible impact of a
change, but changelogs for fixes still tend to say what the code does,
why that's wrong and what the patch changes, and stop there. Whoever
has to decide if the fix needs backporting is left to work out what
the bug does to a running system.

Say what that means for a bug fix: describe the worst a user can see
and what it takes to trigger it, say so if the bug was never seen to
happen, and say so if it has no visible effect at all. Give the
paragraph a label so people can be pointed at it.

Coding assistants are told to commit a fix with a message that
describes the problem and the solution. Add the user-visible impact to
that list and point them at the section.

Suggested-by: Andrew Morton <akpm@linux-foundation.org>
Link: https://lore.kernel.org/r/20261111171055.527b4bf3da705367bc78a64c@linux-foundation.org
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
 Documentation/process/coding-assistants.rst  |  6 ++++--
 Documentation/process/submitting-patches.rst | 11 +++++++++++
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index 509dbf23a099b..ef01ce8d0ff91 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -63,8 +63,10 @@ these steps:
    re-running a complete analysis; drop any fix that doesn't work and try
    another one. The fix must not add build warnings and must pass the
    checkpatch.pl checks (see submitting-patches.rst).
-6. Commit the working fix with a detailed message describing the problem, the
-   solution and a Fixes tag. Do not add a Signed-off-by tag.
+6. Commit the working fix with a detailed message describing the problem, its
+   user-visible impact (see "Describe your changes" in
+   Documentation/process/submitting-patches.rst), the solution and a Fixes
+   tag. Do not add a Signed-off-by tag.
 7. Identify the maintainers and lists using scripts/get_maintainer.pl.
    Documentation/process/security-bugs.rst shows how to do that.
 8. Indicate what could not be done. If the fix could not be built or tested, or
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 9cd19a71e96ec..52cccb08ce896 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -51,6 +51,8 @@ motivated you to do this work.  Convince the reviewer that there is a
 problem worth fixing and that it makes sense for them to read past the
 first paragraph.
 
+.. _user_visible_impact:
+
 Describe user-visible impact.  Straight up crashes and lockups are
 pretty convincing, but not all bugs are that blatant.  Even if the
 problem was spotted during code review, describe the impact you think
@@ -61,6 +63,15 @@ from upstream, so include anything that could help route your change
 downstream: provoking circumstances, excerpts from dmesg, crash
 descriptions, performance regressions, latency spikes, lockups, etc.
 
+For a bug fix, this means saying what the bug does to a running system:
+the worst that a user can see, and what it takes to trigger it.  An
+account of what the code does wrong is not a substitute, as it leaves
+every reader to work the consequences out again.  If the bug was found
+by review or by a tool and has never been seen to happen, say so.  If
+it has no effect that a user could notice, say that too.  Maintainers
+and the people looking after stable trees decide from this whether the
+fix needs to be backported.
+
 Quantify optimizations and trade-offs.  If you claim improvements in
 performance, memory consumption, stack footprint, or binary size,
 include numbers that back them up.  But also describe non-obvious

base-commit: 2138148bf44fd84d3e0a863f0e8cb3627cdcc606
-- 
2.53.0


             reply	other threads:[~2026-11-16 19:14 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-16 19:14 Sasha Levin [this message]
2026-11-16 19:34 ` Andrew Morton
2026-11-16 19:49   ` Willy Tarreau
2026-11-16 19:52   ` Sasha Levin
2026-11-16 19:58     ` Andrew Morton
2026-11-16 20:01       ` Willy Tarreau
2026-11-16 19:47 ` Willy Tarreau

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261116191436.188098-1-sashal@kernel.org \
    --to=sashal@kernel.org \
    --cc=akpm@linux-foundation.org \
    --cc=corbet@lwn.net \
    --cc=gregkh@linuxfoundation.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=rdunlap@infradead.org \
    --cc=skhan@linuxfoundation.org \
    --cc=tytso@mit.edu \
    --cc=w@1wt.eu \
    --cc=workflows@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®