threads / patch / 61839

patchReviewingGuidelines: encourage positive reviews more

Subject: [PATCH] ReviewingGuidelines: encourage positive reviews more

## tl;dr

8 messages between Jul 24, 2024 and Jul 26, 2024. Diffs are folded; open one to read it.

replies: 7people: 4as markdown or json

Junio C Hamano· Jul 24, 2024, 21:14 UTC · lore

I saw some contributors hesitate to give a positive review on patches by their coworkers. When written well, a positive review does not have to be a hollow "looks good" that rubber stamps an otherwise useless approval on a topic that is not interesting to anybody.

Let's add a few paragraphs to encourage positive reviews, which is a bit harder to give than a review to point out things to improve.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/ReviewingGuidelines.txt | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)
Show changes to diff +21 −4
diff --git c/Documentation/ReviewingGuidelines.txt w/Documentation/ReviewingGuidelines.txt
index 515d470d23..f78146a410 100644
--- c/Documentation/ReviewingGuidelines.txt
+++ w/Documentation/ReviewingGuidelines.txt
@@ -72,12 +72,29 @@ guidance, and concrete tips for interacting with patches on the mailing list.
   could fix it. This not only helps the author to understand and fix the issue,
   it also deepens and improves your understanding of the topic.
 
-- Reviews do not need to exclusively point out problems. Feel free to "think out
+- Reviews do not need to exclusively point out problems.  Positive
+  reviews indicate that it is not only the original author of the
+  patches who care about the issue the patches address, and are
+  highly encouraged.
+
+- Do not hesitate to give positive reviews on a series from your
+  work coleague.  If your positive review is written well, it will
+  not make you look as if you two are representing corporate
+  interest on a series that is otherwise uninteresting to other
+  community members.
+
+- Write a positive review in such a way that others can understand
+  why you support the goal, the approach, and the implementation the
+  patches taken.  Make sure to demonstrate that you thoroughly read
+  the series and understood problem area well enough to be able to
+  say if the patches are written well.  Feel free to "think out
   loud" in your review: describe how you read & understood a complex section of
   a patch, ask a question about something that confused you, point out something
-  you found exceptionally well-written, etc. In particular, uplifting feedback
-  goes a long way towards encouraging contributors to participate more actively
-  in the Git community.
+  you found exceptionally well-written, etc.
+
+- In particular, uplifting feedback goes a long way towards
+  encouraging contributors to participate more actively in the Git
+  community.
 
 ==== Performing your review
 - Provide your review comments per-patch in a plaintext "Reply-All" email to the
Eric Sunshine· Jul 24, 2024, 21:39 UTC · re: Junio C Hamano · lore

Re: [PATCH] ReviewingGuidelines: encourage positive reviews more

On Wed, Jul 24, 2024 at 5:14 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 9 quoted lines
> Let's add a few paragraphs to encourage positive reviews, which is a
> bit harder to give than a review to point out things to improve.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> diff --git c/Documentation/ReviewingGuidelines.txt w/Documentation/ReviewingGuidelines.txt
> @@ -72,12 +72,29 @@ guidance, and concrete tips for interacting with patches on the mailing list.
> +- Do not hesitate to give positive reviews on a series from your
> +  work coleague.  If your positive review is written well, it will
s/coleague/colleague/
> +  not make you look as if you two are representing corporate
> +  interest on a series that is otherwise uninteresting to other
> +  community members.
Patrick Steinhardt· Jul 25, 2024, 06:51 UTC · re: Junio C Hamano · lore

Re: [PATCH] ReviewingGuidelines: encourage positive reviews more

On Wed, Jul 24, 2024 at 02:14:37PM -0700, Junio C Hamano wrote:
Show 5 quoted lines
> I saw some contributors hesitate to give a positive review on
> patches by their coworkers.  When written well, a positive review
> does not have to be a hollow "looks good" that rubber stamps an
> otherwise useless approval on a topic that is not interesting to
> anybody.

Oh, yes, this addition is very welcome indeed! It's a painpoint of ours at GitLab, and folks were indeed quite unsure about how to handle positive reviews. I was trying to guide them into the direction of "reverbalizing" and "thinking out aloud" parts of a patch series that are tricky in order to demonstrate that they have indeed read through the patches and understand them. Having all of this written down explicitly should hopefully help them.

Except for the typo mentioned by Eric I don't have anything else to add. Thanks!

Patrick
Derrick Stolee· Jul 25, 2024, 13:31 UTC · re: Patrick Steinhardt · lore

Re: [PATCH] ReviewingGuidelines: encourage positive reviews more

On 7/25/24 2:51 AM, Patrick Steinhardt wrote:
Show 14 quoted lines
> On Wed, Jul 24, 2024 at 02:14:37PM -0700, Junio C Hamano wrote:
>> I saw some contributors hesitate to give a positive review on
>> patches by their coworkers.  When written well, a positive review
>> does not have to be a hollow "looks good" that rubber stamps an
>> otherwise useless approval on a topic that is not interesting to
>> anybody.
> 
> Oh, yes, this addition is very welcome indeed! It's a painpoint of ours
> at GitLab, and folks were indeed quite unsure about how to handle
> positive reviews. I was trying to guide them into the direction of
> "reverbalizing" and "thinking out aloud" parts of a patch series that
> are tricky in order to demonstrate that they have indeed read through
> the patches and understand them. Having all of this written down
> explicitly should hopefully help them.

I'll add the perspective of my experience here that this is a good pattern to follow. One thing that also helps is to avoid doing an "internal review" for experienced contributors.

When Microsoft was first building up new contributors in this space, we were overcautious and performed an internal review before going to the mailing list. While this is good for a contributor's first series, it loses the benefits of doing review in the open.

A positive review is great. A constructive review that improves the series is even better.

> Except for the typo mentioned by Eric I don't have anything else to add.
> Thanks!
Same. Thanks for adding this to the official guidelines.

Thanks, -Stolee

Patrick Steinhardt· Jul 25, 2024, 14:11 UTC · re: Derrick Stolee · lore

Re: [PATCH] ReviewingGuidelines: encourage positive reviews more

On Thu, Jul 25, 2024 at 09:31:46AM -0400, Derrick Stolee wrote:
Show 19 quoted lines
> On 7/25/24 2:51 AM, Patrick Steinhardt wrote:
> > On Wed, Jul 24, 2024 at 02:14:37PM -0700, Junio C Hamano wrote:
> > > I saw some contributors hesitate to give a positive review on
> > > patches by their coworkers.  When written well, a positive review
> > > does not have to be a hollow "looks good" that rubber stamps an
> > > otherwise useless approval on a topic that is not interesting to
> > > anybody.
> > 
> > Oh, yes, this addition is very welcome indeed! It's a painpoint of ours
> > at GitLab, and folks were indeed quite unsure about how to handle
> > positive reviews. I was trying to guide them into the direction of
> > "reverbalizing" and "thinking out aloud" parts of a patch series that
> > are tricky in order to demonstrate that they have indeed read through
> > the patches and understand them. Having all of this written down
> > explicitly should hopefully help them.
> 
> I'll add the perspective of my experience here that this is a good
> pattern to follow. One thing that also helps is to avoid doing an
> "internal review" for experienced contributors.

Absolutely! We originally had an internal review first, but I also changed that procedure earlier this year. Now we have an optional internal review in case people aren't yet all that familiar with the mailing list workflow, but more experienced contributors should send their patches to the mailing list directly.

For one this has sped up our own processes. But second, it allows reviewers to get more exposure to the mailing list as they are also encouraged to always review on the mailing list directly.

> When Microsoft was first building up new contributors in this space,
> we were overcautious and performed an internal review before going
> to the mailing list. While this is good for a contributor's first
> series, it loses the benefits of doing review in the open.
Same.
Patrick
Junio C Hamano· Jul 25, 2024, 15:49 UTC · re: Junio C Hamano · lore

[PATCH v2] ReviewingGuidelines: encourage positive reviews more

I saw some contributors hesitate to give a positive review on patches by their coworkers. When written well, a positive review does not have to be a hollow "looks good" that rubber stamps an useless approval on a topic that is not interesting to others.

Let's add a few paragraphs to encourage positive reviews, which is a bit harder to give than a review to point out things to improve.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 * Thanks for comments on the initial version.  I spotted a few
   typoes and grammos to fix, so here is a (hopefully final) update.
 Documentation/ReviewingGuidelines.txt | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)
Show changes to Documentation/ReviewingGuidelines.txt +21 −4
diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.txt
index 515d470d23..6534643cff 100644
--- a/Documentation/ReviewingGuidelines.txt
+++ b/Documentation/ReviewingGuidelines.txt
@@ -72,12 +72,29 @@ guidance, and concrete tips for interacting with patches on the mailing list.
   could fix it. This not only helps the author to understand and fix the issue,
   it also deepens and improves your understanding of the topic.
 
-- Reviews do not need to exclusively point out problems. Feel free to "think out
+- Reviews do not need to exclusively point out problems.  Positive
+  reviews indicate that it is not only the original author of the
+  patches who care about the issue the patches address, and are
+  highly encouraged.
+
+- Do not hesitate to give positive reviews on a series from your
+  work colleague.  If your positive review is written well, it will
+  not make you look as if you two are representing corporate
+  interest on a series that is otherwise uninteresting to other
+  community members and shoving it down their throat.
+
+- Write a positive review in such a way that others can understand
+  why you support the goal, the approach, and the implementation the
+  patches took.  Make sure to demonstrate that you did thoroughly read
+  the series and understood problem area well enough to be able to
+  say that the patches are written well.  Feel free to "think out
   loud" in your review: describe how you read & understood a complex section of
   a patch, ask a question about something that confused you, point out something
-  you found exceptionally well-written, etc. In particular, uplifting feedback
-  goes a long way towards encouraging contributors to participate more actively
-  in the Git community.
+  you found exceptionally well-written, etc.
+
+- In particular, uplifting feedback goes a long way towards
+  encouraging contributors to participate more actively in the Git
+  community.
 
 ==== Performing your review
 - Provide your review comments per-patch in a plaintext "Reply-All" email to the

Interdiff:
  diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.txt
  index 31fd60aadf..6534643cff 100644
  --- a/Documentation/ReviewingGuidelines.txt
  +++ b/Documentation/ReviewingGuidelines.txt
  @@ -81,13 +81,13 @@ guidance, and concrete tips for interacting with patches on the mailing list.
     work colleague.  If your positive review is written well, it will
     not make you look as if you two are representing corporate
     interest on a series that is otherwise uninteresting to other
  -  community members.
  +  community members and shoving it down their throat.
   
   - Write a positive review in such a way that others can understand
     why you support the goal, the approach, and the implementation the
  -  patches taken.  Make sure to demonstrate that you thoroughly read
  +  patches took.  Make sure to demonstrate that you did thoroughly read
     the series and understood problem area well enough to be able to
  -  say if the patches are written well.  Feel free to "think out
  +  say that the patches are written well.  Feel free to "think out
     loud" in your review: describe how you read & understood a complex section of
     a patch, ask a question about something that confused you, point out something
     you found exceptionally well-written, etc.

-- 
2.46.0-rc2-56-g5eee0f42f3
Patrick Steinhardt· Jul 26, 2024, 12:22 UTC · re: Junio C Hamano · lore

Re: [PATCH v2] ReviewingGuidelines: encourage positive reviews more

On Thu, Jul 25, 2024 at 08:49:34AM -0700, Junio C Hamano wrote:
Show 9 quoted lines
> I saw some contributors hesitate to give a positive review on
> patches by their coworkers.  When written well, a positive review
> does not have to be a hollow "looks good" that rubber stamps an
> useless approval on a topic that is not interesting to others.
> 
> Let's add a few paragraphs to encourage positive reviews, which is a
> bit harder to give than a review to point out things to improve.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>

This version looks good to me (well, the first version already did). Thanks!

Patrick
Junio C Hamano· Jul 26, 2024, 20:20 UTC · re: Patrick Steinhardt · lore

Re: [PATCH v2] ReviewingGuidelines: encourage positive reviews more

Patrick Steinhardt <ps@pks.im> writes:
Show 13 quoted lines
> On Thu, Jul 25, 2024 at 08:49:34AM -0700, Junio C Hamano wrote:
>> I saw some contributors hesitate to give a positive review on
>> patches by their coworkers.  When written well, a positive review
>> does not have to be a hollow "looks good" that rubber stamps an
>> useless approval on a topic that is not interesting to others.
>> 
>> Let's add a few paragraphs to encourage positive reviews, which is a
>> bit harder to give than a review to point out things to improve.
>> 
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>
> This version looks good to me (well, the first version already did).
> Thanks!
Thanks; will mark for 'next'.

← back to recent threads