Re: [PATCH v4] MyFirstContribution: refrain from self-iterating too much

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

Torsten Bögershausen <tboegi@web.de> writes:

>> +While waiting for review comments, you may find mistakes in your initial
>> +patch, or perhaps realize a different and better way to achieve the goal
>> +of the patch. In this case you may communicate your findings to other
>> +reviewers as follows:
>> +
>> + - If the mistakes you found are minor, send a reply to your patch as if
>> +   you were a reviewer and mention that you will fix them in an
>> +   updated version.
>> +
>> + - On the other hand, if you think you want to change the course so
>> +   drastically that reviews on the initial patch would be a waste of
>> +   time (for everyone involved), retract the patch immediately with
>> +   a reply like "I am working on a much better approach, so please
>> +   ignore this patch and wait for the updated version."
>> +
> (That's all good)
>
>
>> +Now, the above is a good practice if you sent your initial patch
>> +prematurely without polish.  But a better approach of course is to avoid
>> +sending your patch prematurely in the first place.
>
> That is of course a good suggestion.
> I wonder, how much a first time contributor knows about "polishing",
> in the Git sense ?

I do not know if "without polish" has any strong "Git sense" to
begin with.  The actions the contributor would have done, referred
to as "the above", are the result of re-reading their own patches
and re-thinking their own approaches, which led them to discover
fixes and alternative solutions, and I was hoping that "without
polish" would be understood by anybody to mean "a version that did
not go through such proofreading" without knowing much about how we
develop our patches.

I am OK to just say "sent your initial patch prematurely" and
without "without polish".  I do think it would make the resulting
text encourage less strongly to proofread their own patches before
sending them, but if you think "polish" may not be understood, I am
fine with such a copyediting.  Or using some alternative phrases is
also fine, if it improves our chances to be understood better.

> From my experience, the polishing is or could be a learning process,
> which needs interaction with the reviewers.

Yes, once they see what valuable insight reviewers offer, in their
next topic, they will learn to stop and think before sending the
fresh-off-the-press version without sleeping on it a bit.

> Would it make sense to remove the sentences above and ask people
> to mark their patch with RFC ?

I doubt it.  Nobody will stay newbie forever.  If they do not know
what kind of flaws to look for and how to find them themselves in
their work, that is perfectly OK and they can just send a regular
PATCH.  A reviewer hopefully will notice and point out that it is
not yet beyond RFC quality if that is the case, but this document
should not be suggesting that before seeing their work ;-)

> Or is this all too much bikeshedding, IOW I am happy with V4 as is.

Thanks.