Re: What's cooking in git.git (Mar 2024, #05; Tue, 19)

[Junio C Hamano <gitster@pobox.com>]

"Brian Lyles" <brianmlyles@gmail.com> writes:

> Yes, I suspect you are right. I think the cover letter would be a good
> start at the very least. Would you welcome a patch to
> 'Documentation/SubmittingPatches' that adds a new expectation for this,
> or do you think this would be best handled yourself? I am interested in
> contributing but, as I'm sure you've noticed, I'm also quite new to the
> project =)

I'd prefer to start with a much less official "experimental" launch
of such a new workflow, instead of adding an unproven idea as if it
is a new hard requirement to the SubmittingPatches document.  If it
works well, we can write it down later.

But even a soft launch needs some way to advertise it to the target
audience, and the SubmittingPatches document is the only sensible
place to do so.  So, perhaps do something like this?  I dunno.

------- >8 ------------- >8 ------------- >8 -------
Subject: SubmittingPatches: release-notes entry experiment

It has been the maintainer's task to prepare the description of each
topic listed in the "What's cooking" report.  The description is
automatically picked up from the "What's cooking" report and used in
the commit log message of the merge commit when the topic is merged
into integration branches.  These commit log messges of the merge
commits are then propagated to the release notes.

The original author of a topic may be in the best position to write
the initial description of a topic, but we so far lacked a formal
channel for the author to tell what description to use.  The usual
procedure has been to see the topic described in "What's cooking"
report, and then either complain about inaccurate explanation and/or
offer a rewrite.

Let's try an experiment to optionally let the author propose the one
paragraph description when the topic is submitted.  Pick the cover
letter as the logical place to do so, and describe an experimental
workflow in the SubmittingPatches document.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 [for what's cooking]
 * An experimental procedure for a topic author to propose the topic
   description to be used in "What's cooking" report and in the
   release notes have been added to the SubmittingPatches document.

 Documentation/SubmittingPatches | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git i/Documentation/SubmittingPatches w/Documentation/SubmittingPatches
index e734a3f0f1..05e15b9436 100644
--- i/Documentation/SubmittingPatches
+++ w/Documentation/SubmittingPatches
@@ -459,6 +459,17 @@ an explanation of changes between each iteration can be kept in
 Git-notes and inserted automatically following the three-dash
 line via `git format-patch --notes`.
 
+[[a-paragraph-summary]]
+
+*This is EXPERIMENTAL*.  When sending a topic, you can propose one
+paragraph summary that appears in the "What's cooking" report when it
+is picked up to explain the topic.  If you choose to do so, please
+write 2-5 lines of a paragraph that will fit well in our release notes
+(see Documentation/RelNotes/* directory for examples), and put it in
+the cover letter, clearly marked as such.  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.
 Do not let your e-mail client send quoted-printable.  Do not let