[PATCH v4] docs: submitting-patches: say which commit a Fixes tag names

[PATCH v4] docs: submitting-patches: say which commit a Fixes tag names

[Sasha Levin]

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.

Say that the tag names the commit that introduced the bug, that a
later commit that exposed it gets a tag too, as handling-regressions.rst
already asks for the commit causing a regression, and that each commit
that introduced the bug separately gets its own tag. Say that the tags
tell the stable team which trees need the fix, and that trees without
any of the tagged commits do not.

Link: https://lore.kernel.org/r/c3ce794d-1ac2-4ef3-9e5c-1e171bd77a89@leemhuis.info
Link: https://lore.kernel.org/r/20261013003535-mutt-send-email-mst@kernel.org
Link: https://lore.kernel.org/r/atCI4q2HvqVXOag1@stanley.mountain
Link: https://lore.kernel.org/r/bcef59f8-33fe-4bbe-8429-307630dc6bb5@leemhuis.info
Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
v4:
 - Split out of the agents skills series, where this was patch 2/7 of v3:
   https://lore.kernel.org/r/20261016152828.3765695-3-sashal@kernel.org
 - Take Thorsten's rewording. A later commit that exposed the bug now
   gets a Fixes: tag too, as handling-regressions.rst already asks.

 Documentation/process/submitting-patches.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 7ae79452e1b46..33e8e7f8f5fa2 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -608,6 +608,14 @@ 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. When using ``git blame`` to find it,
+do not settle on a commit that only moved the code. If a later commit exposed
+an older bug, add a Fixes: tag for that commit too. If the same bug was
+introduced separately by more than one commit, add a Fixes: tag for each. 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.
+
 Note: Attaching a Fixes: tag does not subvert the stable kernel rules
 process nor the requirement to Cc: stable@vger.kernel.org on all stable
 patch candidates. For more information, please read

base-commit: 3857c2fe5449541e24afc5efdb0f81a8a8f9a3a0
-- 
2.53.0

Re: [PATCH v4] docs: submitting-patches: say which commit a Fixes tag names

[Daniel Pereira]

On Tue, Oct 20, 2026, Sasha Levin wrote:
> +Name the commit that introduced the bug. When using ``git blame`` to find it,
> +do not settle on a commit that only moved the code. If a later commit exposed
> +an older bug, add a Fixes: tag for that commit too. If the same bug was
> +introduced separately by more than one commit, add a Fixes: tag for each.

Hi Sasha,

I went through v4 against the tree (docs-next at f857ff5bf):

- the new paragraph sits between the description of the Fixes: tag and
the existing "Note:" about the stable rules, and reads well there;
- handling-regressions.rst does ask for this ("Add a "Fixes:" tag to
specify the commit causing the regression"), so the reference in the
changelog is accurate;
- I built the process documentation with the patch applied and it adds
no new warnings.

One thing for information only: checkpatch --strict reports the
"Assisted-by: LLM" trailer ("Non-standard signature" and "Unrecognized
email address: 'LLM'"), because Documentation/process/ in docs-next does
not describe that tag. If it is defined in the agents series or in
another tree, please ignore this.

Reviewed-by: Daniel Pereira <danielmaraboo@gmail.com>

Thanks,
Daniel

Re: [PATCH v4] docs: submitting-patches: say which commit a Fixes tag names

[Jonathan Corbet]

Sasha Levin <sashal@kernel.org> writes:

> 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.
>
> Say that the tag names the commit that introduced the bug, that a
> later commit that exposed it gets a tag too, as handling-regressions.rst
> already asks for the commit causing a regression, and that each commit
> that introduced the bug separately gets its own tag. Say that the tags
> tell the stable team which trees need the fix, and that trees without
> any of the tagged commits do not.
>
> Link: https://lore.kernel.org/r/c3ce794d-1ac2-4ef3-9e5c-1e171bd77a89@leemhuis.info
> Link: https://lore.kernel.org/r/20261013003535-mutt-send-email-mst@kernel.org
> Link: https://lore.kernel.org/r/atCI4q2HvqVXOag1@stanley.mountain
> Link: https://lore.kernel.org/r/bcef59f8-33fe-4bbe-8429-307630dc6bb5@leemhuis.info
> Assisted-by: LLM
> Signed-off-by: Sasha Levin <sashal@kernel.org>
> ---
> v4:
>  - Split out of the agents skills series, where this was patch 2/7 of v3:
>    https://lore.kernel.org/r/20261016152828.3765695-3-sashal@kernel.org
>  - Take Thorsten's rewording. A later commit that exposed the bug now
>    gets a Fixes: tag too, as handling-regressions.rst already asks.
>
>  Documentation/process/submitting-patches.rst | 8 ++++++++
>  1 file changed, 8 insertions(+)

Applied, thanks.

jon