From: Dragan Simic <dsimic@manjaro.org>
Date: Tue, 26 Mar 2024 07:43:08 GMT
Subject: Re: [PATCH v2] SubmittingPatches: release-notes entry experiment
Message-ID: <506be88207b63ed25067c374d3da8c09@manjaro.org>
In-Reply-To: <xmqq8r26eyva.fsf@gitster.g>

On 2024-03-25 23:21, Junio C Hamano wrote:
> 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>

Looking good to me.

Reviewed-by: Dragan Simic <dsimic@manjaro.org>

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