[PATCH 0/2] SubmittingPatches: guidance for topic names and multi-series efforts

[PATCH 0/2] SubmittingPatches: guidance for topic names and multi-series efforts

[Taylor Blau]

A note to the maintainer, I suggest queueing this as:

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

---

In [1], Junio suggested a few points to stress in our SubmittingPatches
documentation, which are:

 - Mentioning what topics not in 'master' your patches depend on.
 - Suggesting one-line summaries for topics to be used as a topic
   branch name.
 - Describing your topic in the context of a multi-series effort.

The first is already covered by 0a02ca2383 (SubmittingPatches:
simplify guidance for choosing a starting point, 2023-07-14), but the
latter two are not.

The two patches part of this series address the latter two
suggestions.

(As an aside, we should consider whether or not the experiment started
in d255105c99 (SubmittingPatches: release-notes entry experiment,
2024-03-25) can yet be declared a success, and if so, graduate it.)

Thanks in advance for your review!

[1]: https://lore.kernel.org/git/xmqqcy7a5gnb.fsf@gitster.g/

Taylor Blau (2):
  SubmittingPatches: extend release-notes experiment to topic names
  SubmittingPatches: guidance for multi-series efforts

 Documentation/SubmittingPatches | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)


base-commit: 45547b60aca32b45d2f1ef93462cf9df28637c13
-- 
2.51.0.435.gf7a65e208c7

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

[Taylor Blau]

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.

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Taylor Blau <me@ttaylorr.com>
---
 Documentation/SubmittingPatches | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

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

[PATCH 2/2] SubmittingPatches: guidance for multi-series efforts

[Taylor Blau]

Occasionally there are efforts to contribute to the Git project that
span more than one patch series in order to achieve a broader goal. By
convention, the maintainer has typically suffixed the topic names with
"-part-one", or "-part-1" and so on.

Document that convention and suggest some guidance on how to structure
proposed topic names for multi-series efforts.

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Taylor Blau <me@ttaylorr.com>
---
 Documentation/SubmittingPatches | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index f48688e3700..d620bd93bd9 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -593,6 +593,14 @@ 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.
 
+[[multi-series-efforts]]
+If your patch series is part of a larger effort spanning multiple
+patch series, briefly describe the broader goal, and state where the
+current series fits into that goal.  If you are suggesting a topic
+name as in <<the-topic-summary, section above>>, consider
+"XX/the-broader-goal-part-one", "XX/the-broader-goal-part-two", and so
+on.
+
 [[attachment]]
 Do not attach the patch as a MIME attachment, compressed or not.
 Do not let your e-mail client send quoted-printable.  Do not let
-- 
2.51.0.435.gf7a65e208c7

Re: [PATCH 0/2] SubmittingPatches: guidance for topic names and multi-series efforts

[Junio C Hamano]

Taylor Blau <me@ttaylorr.com> writes:

> (As an aside, we should consider whether or not the experiment started
> in d255105c99 (SubmittingPatches: release-notes entry experiment,
> 2024-03-25) can yet be declared a success, and if so, graduate it.)

Thanks.  I haven't seen this used very often, though.  Perhaps it
was a failed experiment that needs to be retracted?

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

[Kristoffer Haugsbakk]

On Tue, Oct 7, 2025, at 23:39, Taylor Blau wrote:
> 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.

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

> +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/

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

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

Hmph, but the paragraphs that eventually go into RelNotes are not
commit log messages.  "Extend the protocol A to achieve X" is what
we would write in our proposed log messages, but after such a patch
achieves X by extending the protocol A, we'd report it in our
release notes by saying something ike "The protocol A was extended
in such and such way to achieve X".

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

Oh, that's a new theory.  So you are saying that authors may have
tried but I (and others) failed to notice?  It cetainly is possible.

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

[Taylor Blau]

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

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

[Taylor Blau]

On Wed, Oct 08, 2025 at 01:51:24PM -0700, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
> > 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.
>
> Hmph, but the paragraphs that eventually go into RelNotes are not
> commit log messages.  "Extend the protocol A to achieve X" is what
> we would write in our proposed log messages, but after such a patch
> achieves X by extending the protocol A, we'd report it in our
> release notes by saying something ike "The protocol A was extended
> in such and such way to achieve X".

Fair, though I think the existing documentation suffers from the same
issue. It says both:

  you can propose a one-paragraph summary that should appear in the
  "What's cooking" report

and:

  Please write a 2-5 line paragraph that will fit well in our release
  notes.

I think that's a separate issue that we should clarify as a prerequisite
to the two patches proposed here.

> > 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.
>
> Oh, that's a new theory.  So you are saying that authors may have
> tried but I (and others) failed to notice?  It cetainly is possible.

Certainly possible indeed, but I am not so sure this is happening. At
least from the series that I have looked at since this experiment was
introduced, I have seen vanishingly few examples of contributors
following the process suggested here.

Perhaps I am missing them too, but my sense is that it's likelier that
contributors just simply aren't doing this rather than doing it and both
of us are not noticing it.

That may be an argument for dropping this section entirely and declaring
the experiment as having failed?

Thanks,
Taylor

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

[Kristoffer Haugsbakk]

On Wed, Oct 8, 2025, at 23:20, Taylor Blau wrote:
>[snip]
> 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?
>

Sorry. I tried to say that: I don’t think “primary” makes it more clear
that one should use the Git author compared to just “author”.

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

I think saying that the cover letter should start with them is just as
much of a prescription as saying that they should be marked with some
paragraph-prefix (and be somewhere in the cover letter). Some people
might prefer to start the letter with what they think are important
call-out information and get to the topic summary later. For example.

>[snip]

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

[Kristoffer Haugsbakk]

On Wed, Oct 8, 2025, at 23:24, Taylor Blau wrote:
>[snip]
>> > 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.
>>
>> Oh, that's a new theory.  So you are saying that authors may have
>> tried but I (and others) failed to notice?  It cetainly is possible.
>
> Certainly possible indeed, but I am not so sure this is happening. At
> least from the series that I have looked at since this experiment was
> introduced, I have seen vanishingly few examples of contributors
> following the process suggested here.
>

I had a look and found one cover letter where I definitely tried to use
the-topic-summary:

    The documentation for git-bundle(1) now prominently covers `--all`, the
    option from git-rev-list(1) that can be used to package all refs.  A
    "Discussion" section has also been added to address the naive backup
    strategy of copying a Git repository manually with cp(1) or some other
    non-Git tool.

    ---

    The part above was for the-topic-summary.

https://lore.kernel.org/git/cover.1731768344.git.code@khaugsbakk.name/

The merge commit message and the release note entry:

     Documentation for "git bundle" saw improvements to more prominently
     call out the use of '--all' when creating bundles.

Contrasted with no judgement.

> [snip]