git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
* [PATCH] MyFirstContribution: refrain from self-iterating too much
@ 2023-01-22  1:51 Junio C Hamano
  2023-01-22  7:11 ` Torsten Bögershausen
  2023-01-23  1:47 ` [PATCH] " Sean Allred
  0 siblings, 2 replies; 7+ messages in thread
From: Junio C Hamano @ 2023-01-22  1:51 UTC (permalink / raw)
  To: git

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

^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH] MyFirstContribution: refrain from self-iterating too much
  2023-01-22  1:51 [PATCH] MyFirstContribution: refrain from self-iterating too much Junio C Hamano
@ 2023-01-22  7:11 ` Torsten Bögershausen
  2023-01-22 16:01   ` Junio C Hamano
  2023-01-23  1:47 ` [PATCH] " Sean Allred
  1 sibling, 1 reply; 7+ messages in thread
From: Torsten Bögershausen @ 2023-01-22  7:11 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

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
>

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] MyFirstContribution: refrain from self-iterating too much
  2023-01-22  7:11 ` Torsten Bögershausen
@ 2023-01-22 16:01   ` Junio C Hamano
  2023-01-22 17:14     ` Junio C Hamano
  2023-01-23  4:18     ` [PATCH v2] " Junio C Hamano
  0 siblings, 2 replies; 7+ messages in thread
From: Junio C Hamano @ 2023-01-22 16:01 UTC (permalink / raw)
  To: Torsten Bögershausen; +Cc: git

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.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] MyFirstContribution: refrain from self-iterating too much
  2023-01-22 16:01   ` Junio C Hamano
@ 2023-01-22 17:14     ` Junio C Hamano
  2023-01-23  4:18     ` [PATCH v2] " Junio C Hamano
  1 sibling, 0 replies; 7+ messages in thread
From: Junio C Hamano @ 2023-01-22 17:14 UTC (permalink / raw)
  To: Torsten Bögershausen; +Cc: git

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.



^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] MyFirstContribution: refrain from self-iterating too much
  2023-01-22  1:51 [PATCH] MyFirstContribution: refrain from self-iterating too much Junio C Hamano
  2023-01-22  7:11 ` Torsten Bögershausen
@ 2023-01-23  1:47 ` Sean Allred
  1 sibling, 0 replies; 7+ messages in thread
From: Sean Allred @ 2023-01-23  1:47 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

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

^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH v2] MyFirstContribution: refrain from self-iterating too much
  2023-01-22 16:01   ` Junio C Hamano
  2023-01-22 17:14     ` Junio C Hamano
@ 2023-01-23  4:18     ` Junio C Hamano
  2023-01-23 17:58       ` Torsten Bögershausen
  1 sibling, 1 reply; 7+ messages in thread
From: Junio C Hamano @ 2023-01-23  4:18 UTC (permalink / raw)
  To: git; +Cc: Torsten Bögershausen

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.

Helped-by: Torsten Bögershausen <tboegi@web.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/MyFirstContribution.txt | 30 +++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index ccfd0cb5f3..3e4f1c7764 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1256,6 +1256,36 @@ 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
+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.")
+
+And give reviewers enough time to process your initial patch before
+sending an updated version.
+
+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 you will follow up with several
+updated "oops, I like this version better than the previous one"
+versions over 2 days, reviewers would much appreciate if a single
+more polished version came 2 days late and that version, that
+contains fewer mistakes, were the only one they need to review.
+
 [[reviewing]]
 === Responding to Reviews
 
-- 
2.39.1-308-g56c8fb1e95


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH v2] MyFirstContribution: refrain from self-iterating too much
  2023-01-23  4:18     ` [PATCH v2] " Junio C Hamano
@ 2023-01-23 17:58       ` Torsten Bögershausen
  0 siblings, 0 replies; 7+ messages in thread
From: Torsten Bögershausen @ 2023-01-23 17:58 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

On Sun, Jan 22, 2023 at 08:18:05PM -0800, Junio C Hamano wrote:

The whole thing is much more convenient to read, so to say.
Some nit-picking inline.

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

I think that this is what V1 was about. Review first, send then.
Is there still so much focus on this ?
Or is it more about "what to do when it went wrong?"

How about this, or similar ?

...it.  Encourage developers to wait with a new version too early.
But if they plan to send one later, they are welcome to comment
their own work as they where reviers.


>
> Helped-by: Torsten Bögershausen <tboegi@web.de>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/MyFirstContribution.txt | 30 +++++++++++++++++++++++++++
>  1 file changed, 30 insertions(+)
>
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index ccfd0cb5f3..3e4f1c7764 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1256,6 +1256,36 @@ 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
> +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.")
> +
> +And give reviewers enough time to process your initial patch before
> +sending an updated version.
> +
> +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 you will follow up with several
> +updated "oops, I like this version better than the previous one"
> +versions over 2 days, reviewers would much appreciate if a single
> +more polished version came 2 days late and that version, that
> +contains fewer mistakes, were the only one they need to review.
> +
>  [[reviewing]]
>  === Responding to Reviews
>
> --
> 2.39.1-308-g56c8fb1e95
>

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2023-01-23 18:03 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-01-22  1:51 [PATCH] MyFirstContribution: refrain from self-iterating too much Junio C Hamano
2023-01-22  7:11 ` Torsten Bögershausen
2023-01-22 16:01   ` Junio C Hamano
2023-01-22 17:14     ` Junio C Hamano
2023-01-23  4:18     ` [PATCH v2] " Junio C Hamano
2023-01-23 17:58       ` Torsten Bögershausen
2023-01-23  1:47 ` [PATCH] " Sean Allred

Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).