Re: [boost] Improving review process

Subject: Re: [boost] Improving review process
From: Jeff Garland (jeff_at_[hidden])
Date: 2011-01-14 09:13:26

Dave Abrahams wrote:
> At Fri, 14 Jan 2011 06:29:16 -0700,
> Jeff Garland wrote:
>>> In my vision, the reviews for a library are comments on a wordpress
>>> article, and the library's documentation links to the review article.
>>>
>> I'd actually like to suggest something that might be more direct.
>> Based on a recommendation from fellow boosters at BoostCon last year
>> we acquired and have been using a web based code review tool for the
>> last 10 months.  The impact of this tool has been a dramatic and
>> radical increase in review quality over the email system we had been
>> using -- in large part because all comments/discussion are attached to
>> the actual source code directly for all to see. The tool provides
>> supports the longer review model since someone looking in week 3 of
>> the review can trivially look at all the review comment discussions to
>> that point directly in context with the code.  Authors can also update
>> code during the review to address issues and the comment context (and
>> prior versions are maintained).  Registered reviewers can also receive
>> email notification when other reviewers comment, etc, etc.  Point is,
>> it's a collaboration tool built for code reviews and it works well.
>>
>> The company that provides the tool allows for free use of the tool by
>> open source projects -- so it's something should be possible for
>> boost.  That said, there will be work here to coordinate with the
>> company, setup the boost space and review users, etc.  The tool is
>> also highly configurable so we'd have to establish some usage policies
>> and such.   All items that we would have to address, but I doubt any
>> are a show stoppers.  Course we likely would have to allow folks that
>> want to provide email reviews to continue that way, but overall once
>> you go down this road you won't go back to email.
>>
>> Note that I'm not mentioning the name of the tool just yet because I
>> don't want to violate our 'advertising policies' on the list.  
> 
> I think you're being overly cautious.  Atlassian?

Fair enough:

http://smartbear.com/codecollab.php

>> If there's interest, I can make initial contact with company and
>> get/post the details on how it would work.  I was planning to
>> propose this at BoostCon, but now that it's come up we should start
>> the process now if folks agree.
> 
> Using a code review tool is an awesome idea. Many reviews are not
> attached to code, but you can put review comments in documentation
> just as well.

Documentation is a bit harder unless you are annotating the document source 
directly -- that is, I haven't see a mode in the tool to annotate against 
'rendered html'.

> A couple of things to consider:
> 
> 1. We'd still need a place for overall assessments that don't pertain
>    to specific details.

There's an 'overall comments' section at the top of each review for these 
kinds of comments.

> 2. I know this is a bold predicition, but I think we will be
>    transitioning to GitHub.  It has an enormous momentum in the open
>    source world, is responsive, and will continue to make a lot more
>    sense as Boost is modularized.  GitHub already supports code
>    review.  I think I'd rather go with a tool that requires absolutely
>    no sysadmin on our part, is a known quantity to many already, etc.
> 

I haven't used the github review capabilities here -- so we'd have to evaluate 
what works best.  As for the admin -- it's truly minimal -- basically the same 
as giving someone sandbox access today -- registering an email address so that 
  comment discussions are tracked, etc.  And the author has to upload code to 
the tool -- but a simple paragraph should be about enough to explain it.

Jeff