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

["Brian Lyles" <brianmlyles@gmail.com>]

Hi Junio

On Thu, Mar 21, 2024 at 8:59 PM Junio C Hamano <gitster@pobox.com> wrote:

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

I would agree that it would be hard to advertise without some change
there. I think that documenting an optional opportunity for now before
considering if it should be a requirement later makes sense.

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

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?
I could see relying on any sort of automatic extraction being unreliable
even with such a recommendation so perhaps it's not worth pursuing for
that reason, but I could imagine it may be useful to have a standardized
way to separate this release notes/what's cooking summary from the rest
of the cover letter (which also acts as a summary of the series).

But in general, I think this looks like a good proposal. Thanks!

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

-- 
Thank you,
Brian Lyles