* [PATCH v2] docs: submitting-patches: ask bug fixes for their user-visible impact
@ 2026-11-16 20:05 Sasha Levin
2026-11-17 9:00 ` Greg Kroah-Hartman
2026-11-17 9:27 ` Leon Romanovsky
0 siblings, 2 replies; 3+ messages in thread
From: Sasha Levin @ 2026-11-16 20:05 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Sasha Levin, Andrew Morton, Willy Tarreau, Shuah Khan,
Randy Dunlap, Greg Kroah-Hartman, Theodore Ts'o,
David Hildenbrand, workflows, linux-doc, linux-kernel
"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, in two parts. For users who aren't
looking for the bug: what a normal workload is likely to run into, and
separately the worst case and what it takes to get there. For someone
triggering it on purpose: whether an unprivileged user could do it and
what that would take, since a race that no real workload loses can
still be won by a program written to win it. 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>
Acked-by: Andrew Morton <akpm@linux-foundation.org>
Reviewed-by: Willy Tarreau <w@1wt.eu>
---
Changes since v1:
- Split the bug-fix paragraph into users who aren't looking for the bug
and someone triggering it on purpose (Andrew, Willy).
v1: https://lore.kernel.org/r/20261116191436.188098-1-sashal@kernel.org
Documentation/process/coding-assistants.rst | 6 +++--
Documentation/process/submitting-patches.rst | 23 ++++++++++++++++++++
2 files changed, 27 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..e5f2181e4d663 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,27 @@ 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.
+An account of what the code does wrong is not a substitute, as it leaves
+every reader to work the consequences out again. Cover two cases:
+
+- Users who are not looking for the bug. Say what a normal workload is
+ likely to run into, and separately what the worst case is and what it
+ takes to get there: configuration, hardware, privileges, timing. 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.
+
+- Someone triggering the bug on purpose. Say whether an unprivileged
+ user could do it and what that would take. A race that no normal
+ workload loses can still be won by a program that retries it on every
+ CPU for an hour. If that makes the bug a vulnerability under
+ Documentation/process/threat-model.rst, follow
+ Documentation/process/security-bugs.rst.
+
+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
^ permalink raw reply [flat|nested] 3+ messages in thread* Re: [PATCH v2] docs: submitting-patches: ask bug fixes for their user-visible impact
2026-11-16 20:05 [PATCH v2] docs: submitting-patches: ask bug fixes for their user-visible impact Sasha Levin
@ 2026-11-17 9:00 ` Greg Kroah-Hartman
2026-11-17 9:27 ` Leon Romanovsky
1 sibling, 0 replies; 3+ messages in thread
From: Greg Kroah-Hartman @ 2026-11-17 9:00 UTC (permalink / raw)
To: Sasha Levin
Cc: Jonathan Corbet, Andrew Morton, Willy Tarreau, Shuah Khan,
Randy Dunlap, Theodore Ts'o, David Hildenbrand, workflows,
linux-doc, linux-kernel
On Mon, Nov 16, 2026 at 03:05:15PM -0500, Sasha Levin wrote:
> "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, in two parts. For users who aren't
> looking for the bug: what a normal workload is likely to run into, and
> separately the worst case and what it takes to get there. For someone
> triggering it on purpose: whether an unprivileged user could do it and
> what that would take, since a race that no real workload loses can
> still be won by a program written to win it. 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>
> Acked-by: Andrew Morton <akpm@linux-foundation.org>
> Reviewed-by: Willy Tarreau <w@1wt.eu>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH v2] docs: submitting-patches: ask bug fixes for their user-visible impact
2026-11-16 20:05 [PATCH v2] docs: submitting-patches: ask bug fixes for their user-visible impact Sasha Levin
2026-11-17 9:00 ` Greg Kroah-Hartman
@ 2026-11-17 9:27 ` Leon Romanovsky
1 sibling, 0 replies; 3+ messages in thread
From: Leon Romanovsky @ 2026-11-17 9:27 UTC (permalink / raw)
To: Sasha Levin
Cc: Jonathan Corbet, Andrew Morton, Willy Tarreau, Shuah Khan,
Randy Dunlap, Greg Kroah-Hartman, Theodore Ts'o,
David Hildenbrand, workflows, linux-doc, linux-kernel
On Mon, Nov 16, 2026 at 03:05:15PM -0500, Sasha Levin wrote:
> "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, in two parts. For users who aren't
> looking for the bug: what a normal workload is likely to run into, and
> separately the worst case and what it takes to get there. For someone
> triggering it on purpose: whether an unprivileged user could do it and
> what that would take, since a race that no real workload loses can
> still be won by a program written to win it. 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>
> Acked-by: Andrew Morton <akpm@linux-foundation.org>
> Reviewed-by: Willy Tarreau <w@1wt.eu>
> ---
> Changes since v1:
> - Split the bug-fix paragraph into users who aren't looking for the bug
> and someone triggering it on purpose (Andrew, Willy).
>
> v1: https://lore.kernel.org/r/20261116191436.188098-1-sashal@kernel.org
>
> Documentation/process/coding-assistants.rst | 6 +++--
> Documentation/process/submitting-patches.rst | 23 ++++++++++++++++++++
> 2 files changed, 27 insertions(+), 2 deletions(-)
Sasha,
Since you're already making changes in that area, could you add a sentence
asking reporters to provide the full dmesg stack trace?
Many AI-generated patches reduce it to one or two lines, which gives no
indication of whether the report is genuine or fabricated. Early in the AI
era, I saw some completely fabricated stack traces.
Thanks
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2026-11-17 9:27 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2026-11-16 20:05 [PATCH v2] docs: submitting-patches: ask bug fixes for their user-visible impact Sasha Levin
2026-11-17 9:00 ` Greg Kroah-Hartman
2026-11-17 9:27 ` Leon Romanovsky
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®