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

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

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

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

We do not even know if it is a good idea, so let's start with a
lightweight process that does not burden participants with too much
red tape.  For a series with a cover letter, 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".  The " a
paragraph that is 2-5 lines long, indented by three SPs, whose first
line has SP-asterisk-SP instead" may be a distinct enough style that
it may not require any further marking.