| Message ID | xmqq3583uyk0.fsf@gitster.g (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | MyFirstContribution: refrain from self-iterating too much | expand |
On Sat, Jan 21, 2023 at 05:51:11PM -0800, Junio C Hamano wrote: > Finding mistakes in and improving your own patches is a good idea, > but doing so too quickly is being inconsiderate to reviewers who > have just seen the initial iteration and taking their time to review > it. Encourage new developers to perform such a self review before > they send out their patches, not after. > > Signed-off-by: Junio C Hamano <gitster@pobox.com> > --- > Documentation/MyFirstContribution.txt | 20 ++++++++++++++++++++ > 1 file changed, 20 insertions(+) > > diff --git c/Documentation/MyFirstContribution.txt w/Documentation/MyFirstContribution.txt > index 7c9a037cc2..81dcaedf0c 100644 > --- c/Documentation/MyFirstContribution.txt > +++ w/Documentation/MyFirstContribution.txt > @@ -1136,6 +1136,26 @@ index 88f126184c..38da593a60 100644 > [[now-what]] > == My Patch Got Emailed - Now What? > > +You should wait for your patch to be reviewed by other people in the > +development community. While you are waiting, you may want to > +re-read what you wrote in the patch you already have sent, as if you > +are a reviewer who is helping you to improve your patch. But resist > +the temptation to update the patch and send a new one, until other > +people had enough time to digest your original patch and give you > +their reviews. They may be taking time to give you a carefully > +written review responses and haven't finished it yet. Bombarding > +them with new versions before they have a chance to react to the > +first iteration is being rude to them. > + > +Of course, you still may spot mistakes and rooms for improvements > +after you sent your initial patch. I can't resist the question: After outlining what not to do and why, could there be a hint what to do ? It may be, that the author justs spots a simple typo, or there may be more heavier changes to be done. Should the author just respond to her/his patch as a reviewer does ? Like: Ops, there is a "typax", I should have written "typo". Or: Re-reading my own stuff, I think that things could have been done in a way like this.... Lets wait for more comments before I send out a new version. >+ Learn from that experience to > +make sure that you will do such a self-review _before_ sending your > +patches next time. You do not have to send your patches immediately > +once you finished writing them. It is not a race. Take your time > +to self-review them, sleep on them, improve them before sending them > +out, and do not allow you to send them before you are reasonably > +sure that you won't find more mistakes in them yourself. > + > [[reviewing]] > === Responding to Reviews >
Torsten Bögershausen <tboegi@web.de> writes: >> +Of course, you still may spot mistakes and rooms for improvements >> +after you sent your initial patch. > > I can't resist the question: After outlining what not to do and why, > could there be a hint what to do ? There already is and it is the theme of the next paragraph. People on the list do not have to see your patch immediately after you wrote it. Instead of seeing the initial version right now that is followed by a series of "oops, I like this verison better than the previous one" rerolls over 2 days, reviewers would appreciate if a single more polished version came 2 days late and that version was the only one they need to review. Wait, re-read what you wrote, fix the problems you find locally, all without sending it out until you find no more "oops, that would not work" and simple typos. Sleep on it. Of course, people are not perfect so they may still find issues after they sent their patches out. > It may be, that the author justs spots a simple typo, or there may > be more heavier changes to be done. > > Should the author just respond to her/his patch as a reviewer does ? > Like: > Ops, there is a "typax", I should have written "typo". Follow that with the same "I will fix this typo when I reroll, but I'll wait for reviews from others" as the other one, and it would be the second best thing you could do (the best is to avoid having to say that, of course). > Or: > Re-reading my own stuff, I think that things could have been done > in a way like this.... > Lets wait for more comments before I send out a new version. Again, very good.
Junio C Hamano <gitster@pobox.com> writes: > Torsten Bögershausen <tboegi@web.de> writes: > >> Or: >> Re-reading my own stuff, I think that things could have been done >> in a way like this.... >> Lets wait for more comments before I send out a new version. > > Again, very good. The latter one (different course) needs spearate treatment from the former (typofix). Small corrections without changing course is better communicated with "will fix when I reroll" while a drastic change should warn the readers not to waste their time on the premature initial version, i.e. "I came up with a drastically different and better idea; please ignore the one I just posted and wait for an updated one". I'll sleep on what I rewrote to see if I or other people find better phrasing. Thanks.
First review on this list; let me know if I've missed any decorum :-) Junio C Hamano <gitster@pobox.com> writes: > +Of course, you still may spot mistakes and rooms for improvements > +after you sent your initial patch. Learn from that experience to > +make sure that you will do such a self-review _before_ sending your > +patches next time. You do not have to send your patches immediately > +once you finished writing them. It is not a race. Take your time > +to self-review them, sleep on them, improve them before sending them > +out, and do not allow you to send them before you are reasonably > +sure that you won't find more mistakes in them yourself. Something of a nit: do not allow you to send them... should be do not allow yourself to send them... You're also using 'them' a *lot* which took me for a tumble my first read-through. I lost track of what 'them' actually was. Since this documentation is especially likely to be read by those who are already confused by the process, it may be beneficial to be more explicit at some points: ... patches next time. You do not have to send your patches immediately once you finished writing them. It is not a race. Take your time to review your own patches, sleep on them, and improve them. Do not allow yourself to send out your patches for review before you are reasonably sure you won't find more mistakes in them yourself. -- Thanks for all the work you do on this list; it's much appreciated. -Sean -- Sean Allred
diff --git c/Documentation/MyFirstContribution.txt w/Documentation/MyFirstContribution.txt index 7c9a037cc2..81dcaedf0c 100644 --- c/Documentation/MyFirstContribution.txt +++ w/Documentation/MyFirstContribution.txt @@ -1136,6 +1136,26 @@ index 88f126184c..38da593a60 100644 [[now-what]] == My Patch Got Emailed - Now What? +You should wait for your patch to be reviewed by other people in the +development community. While you are waiting, you may want to +re-read what you wrote in the patch you already have sent, as if you +are a reviewer who is helping you to improve your patch. But resist +the temptation to update the patch and send a new one, until other +people had enough time to digest your original patch and give you +their reviews. They may be taking time to give you a carefully +written review responses and haven't finished it yet. Bombarding +them with new versions before they have a chance to react to the +first iteration is being rude to them. + +Of course, you still may spot mistakes and rooms for improvements +after you sent your initial patch. Learn from that experience to +make sure that you will do such a self-review _before_ sending your +patches next time. You do not have to send your patches immediately +once you finished writing them. It is not a race. Take your time +to self-review them, sleep on them, improve them before sending them +out, and do not allow you to send them before you are reasonably +sure that you won't find more mistakes in them yourself. + [[reviewing]] === Responding to Reviews
Finding mistakes in and improving your own patches is a good idea, but doing so too quickly is being inconsiderate to reviewers who have just seen the initial iteration and taking their time to review it. Encourage new developers to perform such a self review before they send out their patches, not after. Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/MyFirstContribution.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)