Re: [PATCH 1/2] SubmittingPatches: extend release-notes experiment to topic names

[Taylor Blau <me@ttaylorr.com>]

On Wed, Oct 08, 2025 at 06:14:42PM +0200, Kristoffer Haugsbakk wrote:
> > 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.

I wrote it this way to account for individuals listed under the
Co-authored-by trailer. I'm not entirely sure that I'm following the
latter half of this sentence. Could you clarify what you mean?

> 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.

That's fair, though I admittedly dislike the idea of prescribing a
format for the cover letter. It should be clear to those (such as the
maintainer) who are reading the cover letter closely whether or not the
first paragraph (or two) are meant to be used as the topic name/summary.

Perhaps I am in the minority in thinking that, though, in which case I
am happy to continue to discuss/explore other options.

Thanks,
Taylor