Re: [PATCH] docs: submitting-patches: ask bug fixes for their user-visible impact

From: Willy Tarreau

Date: Mon Nov 16 2026 - 14:47:43 EST


Hi Sasha,

On Mon, Nov 16, 2026 at 02:14:36PM -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: 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@xxxxxxxxxxxxxxxxxxxx>
> Link: https://lore.kernel.org/r/20261111171055.527b4bf3da705367bc78a64c@xxxxxxxxxxxxxxxxxxxx
> Signed-off-by: Sasha Levin <sashal@xxxxxxxxxx>
> ---
> 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.
> +

Look good.

Reviewed-by: Willy Tarreau <w@xxxxxx>

I think we can go even further by distinguishing the absolute worst
that can happen from the most likely. When you ask an LLM analyzing
code about a worst case, it doesn't care much about the real world
and will often explain that if the user enable CONFIG_xxx and write
foo under /proc/something and has force-loaded some outdated modules
and has plugged a device emulator into their USB port, then the bug
could indeed get worse. For backports you also want to know whether
innocent users are affected or not.

> 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

Cheers,
Willy