Re: [PATCH v3 2/7] docs: submitting-patches: say which commit a Fixes tag names

[Thorsten Leemhuis <linux@leemhuis.info>]

On 10/16/26 17:28, Sasha Levin wrote:
> The description of the Fixes: tag does not say which commit to name when
> a later commit made an older bug reachable, or when more than one commit
> introduced the same bug, and both questions come up regularly. The
> commit that blame points at is also often one that only moved the code.
> [...]

Thx for this!

> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -608,6 +608,15 @@ which stable kernel versions should receive your fix. This is the preferred
>  method for indicating a bug fixed by the patch. See :ref:`describe_changes`
>  for more details.
>  
> +Name the commit that introduced the bug. ``git blame`` and ``git bisect`` can
> +point at a commit that only moved the code, or that made an older bug
> +reachable. If a later commit made an older bug reachable, name the commit that
> +introduced the bug; a second Fixes: tag for the later commit is fine. If the
> +same bug was introduced separately by more than one commit, add a Fixes: tag
> +for each, but do not add tags for commits that are only suspected. The Fixes:
> +tags tell the stable team which trees need the fix: those that contain one of
> +the tagged commits. Trees that contain none of them do not need it.
> +

How about this instead:

"""
Name the commit that introduced the bug in the first place; hence, when
using ``git blame`` to find it, ensure to not settle on changes that
just moved the code. If the bug was introduced by more than one commit,
add Fixes: tags for each. If some change according to ``git bisect``
exposed a formerly hidden bug, add a Fixes: tag for that change, too. Do
not add tags for commits that are only suspected.
"""

My line of thought here:

* I disliked how ``git blame`` and ``git bisect`` were mixed up, as
those are mostly unrelated in this context.

* After thinking about our recent discussion some more, I think the
Fixes: tag for a change that exposed a bug should be mandatory. That
buys us three things:

 - Everybody that runs into the problem and bisects it will be able to
find fixes for it; without that there might not be even an easy
connection to get from a thread with an earlier report on lore to a fix
posted in a new thread.
 - For my regression tracking efforts this tag is useful, too.
 - It's useful for Linus and maintainers as well, as it allows to
distinguish between "this is a fix we need to apply quickly, as a recent
change exposed the bug" and "this is a fix that can wait till the next
merge window".

* It's a little shorter. Maybe the "according to ``git bisect``" and "a
formerly hidden" could be removed, too.

* Feel free to add the "The Fixes: tags tell the stable team which trees
need the fix: those that contain one of the tagged commits. Trees that
contain none of them do not need it." again, I have no problem with
that. Or maybe strip it down to "These tags allow the stable team and
everybody else to find bug fixes relevant for them." With "everybody
else" I'm thinking of users running into bugs (see above) or downstream
that maintain their own backports.

Ciao, Thorsten