[PATCH v2] SubmittingPatches: release-notes entry experiment

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 25, 2024, 22:21 UTC
Message-ID: <xmqq8r26eyva.fsf@gitster.g>

The "What's cooking" report lists the topics in flight, with a short paragraph descibing what they are about.

Once written, 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.

It has been the maintainer's task to prepare these entries in the "What's cooking" report. Even though the original author of a topic may be in the best position to write the initial description of a topic, we so far lacked a formal channel for the author to suggest what description to use. The usual procedure has been for the author 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>
---
 * 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.

 The above is an example that follows this protocol for a
 single-patch series.

    >> Would it be beneficial to request some specific heading, phrase, or
    >> other structured text such that this summary is obvious, or even easily
    >> extracted with some sort of script? Or is that perhaps overkill for now?
    >
    > ... the rule might end up
    > to be as simple as "When the first paragraph of the message looks
    > like an entry in the Release Notes, it is used as such".

Range-diff:
1:  83f8b69ab9 ! 1:  86b861255b SubmittingPatches: release-notes entry experiment
      ## Documentation/SubmittingPatches ##
     @@ Documentation/SubmittingPatches: an explanation of changes between each iteration can be kept in
    @@ Documentation/SubmittingPatches: an explanation of changes between each iteratio
     +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,
    ++(see Documentation/RelNotes/* directory 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.
     +

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

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e734a3f0f1..e29a3d9a5b 100644
--- a/Documentation/SubmittingPatches
+++ b/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 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.
+
 [[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.44.0-325-g11c821f2f2