Re: [PATCH 1/2] SubmittingPatches: extend release-notes experiment to topic names
On Tue, Oct 7, 2025, at 23:39, Taylor Blau wrote:
Show 5 quoted lines
> In d255105c99 (SubmittingPatches: release-notes entry experiment,
> 2024-03-25), we began an experiment to have contributors suggest a topic
> description to appear in our RelNotes and "What's cooking?" reports.
> Extend that experiment to also welcome suggested topic branch names in
> addition to descriptions.
This is a nice idea for keeping track of the upstream topic.
Show 27 quoted lines
>[snip]
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 86ca7f6a78a..f48688e3700 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -579,14 +579,19 @@ line via `git format-patch --notes`.
> [[the-topic-summary]]
> *This is EXPERIMENTAL*.
>
> -When sending a topic, you can propose a one-paragraph summary that
> -should appear in the "What's cooking" report when it is picked up to
> -explain the topic. If you choose to do so, please write a 2-5 line
> -paragraph that will fit well in our release notes (see many bulleted
> -entries in the Documentation/RelNotes/* files for examples), and make
> -it the first paragraph of the cover letter. For a single-patch
> -series, use the space between the three-dash line and the diffstat, as
> -described earlier.
> +When sending a topic, you can optionally propose a topic name and/or a
> +one-paragraph summary that should appear in the "What's cooking"
> +report when it is picked up to explain the topic. If you choose to do
> +so, please write a 2-5 line paragraph that will fit well in our
> +release notes (see many bulleted entries in the
> +Documentation/RelNotes/* files for examples), and make it the first
> +(or second, if including a suggested topic name) paragraph of the
> +cover letter. If suggesting a topic name, use the format
> +"XX/your-topic-name", where "XX" is a stand-in for the primary
> +author's initials, and "your-topic-name" is a brief, dash-delimited
Is there a precedent for “primary” author? Why not just “author”?
This seems to be referring to the fact that patches might have co-authors (trailers) and similar, or that it could be sent from someone else but the author, but I don’t think this adjective makes it clear that the topic name should stick to the author (in the Git model’s sense) name only.
Show 8 quoted lines
> +description of what your topic does. For a single-patch series, use
> +the space between the three-dash line and the diffstat, as described
> +earlier.
>
> [[attachment]]
> Do not attach the patch as a MIME attachment, compressed or not.
> --
> 2.51.0.435.gf7a65e208c7
I like the format in the cover letter:
* tb/submitting-patches
Extend the experimental protocol used by contributors to propose a
topic branch name in addition to a description, and describe how to
name multi-series efforts. ---
Everything is nicely *delimited* so to speak.
But it was noted[1] that the-topic-summary doesn’t seem to have been used much. That’s not surprising given that the instruction makes the-topic-summary blend in with the rest of the cover letter and doesn’t signal that the author intends for the first paragraph to be used as such. This patch shares the same problem.
I think it would be nice to distinguish these things with some initial paragraph text. In the case of the-topic-summary:
1. Start a paragraph with `Topic summary:`
2. Then continue the paragraph with an explanation that would fit well
in our release notes (see many bulleted entries in the
Documentation/RelNotes/* files for examples). Aim for 2-5 lines.In the case of topic-name:
- Add a paragraph with `Topic name: XX/your-topic-name` where XX is
the author's initials.Then it might be possible to drop “at the start of” *if* the aim of that part is to be able to pick up the intended paragraphs reliably. (Maybe the intent is for the maintainer to be able to read the cover letter in a predictable order.)
🔗 1: https://lore.kernel.org/git/xmqqv7kqgs4x.fsf@gitster.g/
Taylor Blau