Reviewing documentation pull requests

Mon Jun 2 14:06:30 EDT 2014

Hey,

Good conversation. So I think we should explore these two positions a little bit. The question here, I think, is whether or not we want to introduce a formal governance model for our documentation repository.

As background, our current formal process for making changes to critical code repositories (in this case, Infusion) requires that:

1. All changes be submitted via a pull request
2. Someone on the committers team—specifically, someone who isn’t the person making the change--must thoroughly review and push all changes
3. A pull request should be reviewed by someone with experience in the part of the code that was changed

There are many reasons why we follow this formal approach when it comes to source code. The key reasons relate to the fact that changes to code carry the risk of causing:

* Regressions in the software’s functionality
* Errors in the new functionality
* Maintainability problems
* Performance problems

So our formal commit process is intended to strike a balance between ensuring stability and making it easy to improve. Since the risk of problems is so high with code, we’re willing to wait on new features until they have been carefully reviewed by one or more committers. We rely more on process because the risk is very high. This process, as we know, can be slow sometimes.

In the case of our documentation, we should ask ourselves a couple of questions. First, do changes to documentation represent a similar risk? Can a documentation change:

* Be inaccurate?
* Break other parts of the documentation?
* Cause the documentation to become significantly harder to maintain? 
* Cause the documentation to become significantly harder to use?

My impression is that these issues are indeed a concern, but perhaps to a lesser extent than with code. So then the question is, given the risk, do we want to trade off ease of improvement for correctness by introducing a formal process?

Note that we could, if we thought it was worthwhile, create a set of suggestions and recommendations for the documentation team to follow, rather than a formalized, all-or-nothing process. I can imagine those recommendations would include something to the effect of “unless the changes are small, documentation committers should themselves submit them as pull requests and ask for peer review,” without requiring this to be formalized.

I’d like to hear your thoughts, Justin and Antranig (and other members of the documentation team), on these questions.

Colin

On Jun 2, 2014, at 1:07 PM, Justin Obara <obara.justin at gmail.com> wrote:

> I'd argue that it would be a good opportunity to ensure correctness, as well as proper presentation and readability, of our documentation by reviewing it before it made it's way up to master.
> 
> Thanks
> Justin
> 
> On Jun 2, 2014, at 11:26 AM, Antranig Basman <Antranig.Basman at colorado.edu> wrote:
> 
>> I think that we had agreed that those with commit access to the documentation would be able to to push/merge changes without formality. This preserves the existing semantic that we have for edits made to our old documentation in the wiki. I believe this is the model Colin is referring to by the "simple and open process".
>> 
>> Cheers,
>> Antranig
>> 
>> On 02/06/2014 14:05, Justin Obara wrote:
>>> I agree that the committers for Infusion-Docs should not necessarily be the same as those for Infusion. We should probably keep to a similar branch, pull request, merge (with logs) workflow.
>>> 
>>> Thanks
>>> Justin
>>> 
>>> On May 30, 2014, at 4:55 PM, Colin Clark <colinbdclark at gmail.com> wrote:
>>> 
>>>> Hi Anastasia and all,
>>>> 
>>>> I think it’s worthwhile to have a lightweight code review process for documentation pull requests. I’ve enjoyed following the way you’ve all been working so far. I think it would be great to ensure a member of our documentation working group reviews pull requests as they come in, and recruit the developers who worked on a particular feature to also lend a hand with the documentation review process.
>>>> 
>>>> In my opinion, and this is open to debate, the people who can edit and review and push documentation changes to our documentation repo need not be committers to the Infusion repository—we should have a more simple and open process for this. I believe we can create a distinct team in Github to enable more open push access to the repo if we desire.
>>>> 
>>>> Thoughts?
>>>> 
>>>> Colin
>>>> 
>>>> On May 12, 2014, at 11:59 AM, Cheetham, Anastasia <acheetham at ocadu.ca> wrote:
>>>> 
>>>>> 
>>>>> Michelle, Simon and Antranig,
>>>>> 
>>>>> We've been making great progress porting documentation to markdown. We're now faced with the question of who reviews pull requests for documentation. We never really discussed this.
>>>>> 
>>>>> Does anyone have any thoughts on this?
>>>>> 
>>>>> --
>>>>> Anastasia Cheetham     Inclusive Design Research Centre
>>>>> acheetham at ocadu.ca           Inclusive Design Institute
>>>>>                                      OCAD University
>>>>> 
>>>>> _______________________________________________________
>>>>> fluid-work mailing list - fluid-work at fluidproject.org
>>>>> To unsubscribe, change settings or access archives,
>>>>> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
>>>> 
>>>> _______________________________________________________
>>>> fluid-work mailing list - fluid-work at fluidproject.org
>>>> To unsubscribe, change settings or access archives,
>>>> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
>>> 
>>> _______________________________________________________
>>> fluid-work mailing list - fluid-work at fluidproject.org
>>> To unsubscribe, change settings or access archives,
>>> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
>>> 
>> 
>> _______________________________________________________
>> fluid-work mailing list - fluid-work at fluidproject.org
>> To unsubscribe, change settings or access archives,
>> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
> 
> _______________________________________________________
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work