Re: [PATCH 2/2] SubmittingPatches: extend the "flow" section

From: Junio C Hamano <gitster@pobox.com>
Date: May 10, 2024, 15:59 UTC
Message-ID: <xmqqh6f564kp.fsf@gitster.g>
In-Reply-To: <CAOLa=ZS_5+x7_xxppD8BE7RA0X+BFHPm=ffWg4JDgORqR5=sqQ@mail.gmail.com>

Karthik Nayak <karthik.188@gmail.com> writes:

Show 16 quoted lines

>> +=== A not-so ideal patch flow
>> +
>> +To help us understand the reason behind various guidelines given later
>> +in the document, first lets understand how the lifecycle of a typical
>> +patch series for this project goes.
>> +
>> +. You come up with an itch.  You code it up.  You do not need any
>> +  pre-authorization from the project to do so.  Your patches will be
>
> Wouldn't it be better to have the following sentences after the next
> para?
>
> So the flow would be
> - Have an itch. Code it up.
> - Send patches to list.
> - Get reviews.

I am not sure what exactly you are suggesting. "The next para" meaning? The sentence far below that begins with "In the following sections, many techniques and ..."?

Also, "Get reviews" is not a single step that is an end of story, so what you wrote is a bit misleading as a short summary.

The goal of this update is to reduce duplicates by describing a typical life-cycle of a patch series from the inception of an idea to the decision to include it in the next release here, so the proposed "decision making" document can focus on issues at a level larger than a topic of a patch series, and a contributor, especially a new one who wants to give us their first patch series, can learn by only reading these paragraphs how the world works around here with their patch series from the beginning to the end. So what happens after "Get reviews." is a part of the same "flow". Namely these three paragraphs---the original submitter cannot just leave with "now it is their problem" after they get reviews. They are now integral part of the discussion and we expect to see them see the process through.

Show 23 quoted lines

>> +. While the above iterations improve your patches, the maintainer may
>> +  pick the patches up from the list and queue them to the `seen`
>> +  branch, in order to make it easier for people to play with it
>> +  without having to pick up and apply the patches to their trees
>> +  themselves.  Being in `seen` has no other meaning.  Specifically, it
>> +  does not mean the patch was "accepted" in any way.
>> +
>> +. When the discussion reaches a consensus that the latest iteration of
>> +  the patches are in good enough shape, the maintainer includes the
>> +  topic in the "What's cooking" report that are sent out a few times a
>> +  week to the mailing list, marked as "Will merge to 'next'."  This
>> +  decision is primarily made by the maintainer with the help from
>> +  reviewers.
>> +
>> +. Once the patches hit 'next', the discussion can still continue to
>> +  further improve them by adding more patches on top, but by the time
>> +  a topic gets merged to 'next', it is expected that everybody agreed
>> +  that the scope and the basic direction of the topic are appropriate,
>> +  so such an incremental updates are expected to be limited to small
>> +  corrections and polishing.  After a topic cooks for some time (like
>> +  7 calendar days) in 'next' without further tweaks on top, it gets
>> +  merged to the 'master' branch and wait to become part of the next
>> +  major release.

Show 7 quoted lines

>> +Earlier versions of this document outlined a slightly different patch
>> +flow in an idealized world, where the original submitter gathered
>> +agreements from the participants of the discussion and sent the final
>> +"we all agreed that this is the good version--please apply" patches
>> +to the maintainer.  In practice, this almost never happened.  The flow
>> +described above reflects the reality much better and can be considered
>> +the "canonical" procedure to get the patch accepted to the project.

I actually was expecting to hear more comments about this paragraph, which makes a lame excuse for naming the section "A not-so ideal". After sleeping on it, I think it belongs to the log message of this change, not here. Future wanna-be developers do not have to know what process we wanted to have---they benefit from reading what the process _is_ in practice in a more direct way.

>> +In the following sections, many techniques and conventions are listed
>> +to help your patches get reviewed effectively.

Thanks.