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

From: Taylor Blau <me@ttaylorr.com>
Date: Oct 8, 2025, 21:24 UTC
Message-ID: <aObWkRSU5TO9Yvcr@nand.local>
In-Reply-To: <xmqq8qhlf777.fsf@gitster.g>

On Wed, Oct 08, 2025 at 01:51:24PM -0700, Junio C Hamano wrote:

Show 16 quoted lines

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

Show 8 quoted lines

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