Re: [PATCH] Documentation/CommunityGuidelines

[Michael Haggerty <mhagger@alum.mit.edu>]

On 06/12/2013 10:02 PM, Junio C Hamano wrote:
> Michael Haggerty <mhagger@alum.mit.edu> writes:
> 
>> I would prefer a community standards document that looks more like this:
>> ...
>>
>> * Be welcoming to new community participants.  Help them get oriented,
>> and be patient with their questions.  Gently introduce them to our
>> community standards, above all by setting a good example yourself.
> 
> I agree that on-boarding is an important process.
> 
> In addition to the reviews I'd give to regulars, I personally try
> to do some of these things:
> 
>  - Even in a negative review, end the message with "Thanks".  More
>    important is to express that the particular patch is rejected but
>    contributor's future contribution (either a reroll or a separate
>    topic) is welcome.
> 
>    This is free, and there is no reason not to be nice.
> 
>  - Point out problems in a milder way than usual.  Instead of saying
>    "Why is this done like so?", risking to be misinterpreted that I
>    am saying the patch did something wrong and the contributor was a
>    horrible programmer, rephrase it to "Hmph, this may work in such
>    and such cases, but I wonder how well it would in this case?",
>    followed by "How about going this route instead, which would
>    cover all these cases?"
> 
>    Doing so is more time consuming at reviewers' end; once you know
>    the current design well enough, you can immediately smell a wrong
>    approach a lot faster by just looking at code and design in a
>    patch, without having to come up with a concrete example.
> 
>  - Instead of just pointing out minor nits and have the new
>    contributor reroll, point them out, and then show how the patch
>    should have looked like, often after "-- >8 --" and the "From:"
>    line that keeps attribution.
> 
>    Again this is more work at reviewers' end.
> 
> Coaching new contributors, like mentoring GSoC students, is often
> more time consuming than scratching the same itch yourself for any
> reviewer, but it is an investment, which hopefully yields dividend
> in the longer term.

Thanks for these concrete examples / suggestions for reviewers.  I
remember especially that during my first contacts with the Git community
I was very impressed by these very things in your code reviews and in
those of other reviewers.

Are you proposing that your text should find its way into the
CommunityGuidelines in some form?  I hesitate to make the document *so*
long, especially considering that the section for contributors would
then probably also be expanded by a similar amount.  But I think
distilling the advice into one or two sentences, also taking into
account the suggestions of others in this thread, would be a definite
improvement.

When I have time I want to submit some form of CommunityGuidelines as an
explicit patch, and I will try to synthesize all of the suggestions that
have been made.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/