| Message ID | xmqq8rbbbzp2.fsf_-_@gitster.g (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v3] MyFirstContribution: refrain from self-iterating too much | expand |
I was in the process of writing a review but my comments were getting a bit long. So to save you the trouble of applying the suggested changes, I have a scissors patch version at the bottom with the changes applied (you may simply want to read that first). Junio C Hamano <gitster@pobox.com> writes: > +After you sent out your first patch, you may find mistakes in it, or s/you sent/sending Also, add "perhaps realize" after "or". > +a different and better way to achieve the goal of the patch. But > +please resist the temptation to send a new version immediately. > + > + - 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 s/a/the > + updated version. > + > + - On the other hand, if you think you want to change the course so > + drastically that reviews on the initial patch would become > + useless, send a reply to your patch to say so immediately to > + avoid wasting others' time (e.g. "I am working on a better > + approach, so please ignore this patch, and wait for the updated > + version.") How about this wording? - 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." > +Then give reviewers enough time to process your initial patch before > +sending an updated version (unless you retracted the initial patch, > +that is). I think this paragraph should be moved inside the first one above. So it could read something like this: Please give reviewers enough time to process your initial patch before sending an updated version. That is, resist the temptation to send a new version immediately (because it may be the case that others may have already started reviewing your initial version). 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: > +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. OK. > +Keep in mind that people in the development community do not have to > +see your patch immediately after you wrote it. How about just Please be considerate of the time needed by reviewers to examine each new version of your patch. ? > Instead of seeing s/Instead of/Rather than > +the initial version right now, that will be followed by several s/, that will be / ( > +updated "oops, I like this version better than the previous one" s/updated// > +versions over 2 days, reviewers would more appreciate if a single s/versions over 2 days,/patches over 2 days), s/more appreciate/strongly prefer > +polished version came 2 days late and that version with fewer s/2 days late/instead, > +mistakes were the only one they need to review. s/need/would need/ > + > [[reviewing]] > === Responding to Reviews > > -- > 2.41.0-376-gcba07a324d Below is my scissor patch version. --8<---------------cut here---------------start------------->8--- Please give reviewers enough time to process your initial patch before sending an updated version. That is, resist the temptation to send a new version immediately (because it may be the case that others may have already started reviewing your initial version). 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 the 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." 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. Please be considerate of the time needed by reviewers to examine each new version of your patch. Rather than seeing the initial version right now (followed by several "oops, I like this version better than the previous one" patches over 2 days), reviewers would strongly prefer if a single polished version came instead, and that version with fewer mistakes were the only one they would need to review. --8<---------------cut here---------------end--------------->8---
Linus Arver <linusa@google.com> writes: > I was in the process of writing a review but my comments were getting a > bit long. So to save you the trouble of applying the suggested changes, > I have a scissors patch version at the bottom with the changes applied > (you may simply want to read that first). Thanks. I very much like your version over the one you are responding to, except for one minor point. >> +Keep in mind that people in the development community do not have to >> +see your patch immediately after you wrote it. > > How about just > > Please be considerate of the time needed by reviewers to examine > each new version of your patch. > > ? Both give a useful piece of advice, but they are slightly different. > Please be considerate of the time needed by reviewers to examine each > new version of your patch. Rather than seeing the initial version right > now (followed by several "oops, I like this version better than the > previous one" patches over 2 days), reviewers would strongly prefer if a > single polished version came instead, and that version with fewer > mistakes were the only one they would need to review. What I wanted to convey with "we do not need your initial patch immediately" was that it is perfectly fine if the cost of producing the version "reviewers would strongly prefer" is that it takes 2 more days before they see such a more polished version. IOW, adding something like , even if it took 2 more days before they see the version. at the end of the above paragraph was what I wanted to say with "hey, this is not a race. don't focus on sending immediately after you wrote it. nobody is dying to see your patch immediately off the press". Thanks.
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index ccfd0cb5f3..1ede3f8e37 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -1256,6 +1256,37 @@ index 88f126184c..38da593a60 100644 [[now-what]] == My Patch Got Emailed - Now What? +After you sent out your first patch, you may find mistakes in it, or +a different and better way to achieve the goal of the patch. But +please resist the temptation to send a new version immediately. + + - 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 become + useless, send a reply to your patch to say so immediately to + avoid wasting others' time (e.g. "I am working on a better + approach, so please ignore this patch, and wait for the updated + version.") + +Then give reviewers enough time to process your initial patch before +sending an updated version (unless you retracted the initial patch, +that is). + +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. + +Keep in mind that people in the development community do not have to +see your patch immediately after you wrote it. Instead of seeing +the initial version right now, that will be followed by several +updated "oops, I like this version better than the previous one" +versions over 2 days, reviewers would more appreciate if a single +polished version came 2 days late and that version with fewer +mistakes were the only one they need to review. + [[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. After sending a patch that they immediately found mistakes in, they are welcome to comment on them, mentioning what and how they plan to improve them in an updated version, before sending out their updates. Helped-by: Torsten Bögershausen <tboegi@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com> --- * Sorry for a slow update. Even though the topic is about not updating too quickly, this update was long overdue. Not a whole lot changed. Primary change is the later part of the proposed log message, which was helped by Torsten's comments, to which this message is a response to. Documentation/MyFirstContribution.txt | 31 +++++++++++++++++++++++++++ 1 file changed, 31 insertions(+)