Pull Request Review Procedure

Christoph Buchner edited this page Aug 28, 2013 · 3 revisions

Suggested values: (X)=14, (N)=3 and (M)=14

  1. Someone submits a change for discussion:
    1. For small but clear changes, an issue is opened on GitHub describing the bug or feature.
    2. For larger structural changes, an email is sent to the openFrameworks dev list before it becomes an issue.
  2. If the issue is going in the wrong direction, a team member (the Core or section leaders) must comment on the issue within a certain number of days (X). If the submitter writes code before getting any feedback, they need to understand that there is no expectation that their code will be merged. So there are three possibilities:
    1. there is no approval or rejection, and a PR may not be accepted further down the line
    2. a team member approves the proposal, and a matching PR is eventually accepted
    3. a team member rejects the proposal, and the issue is closed or rewritten until that team member is satisfied.
  3. A pull request is submitted.
  4. The GitHub leader (or, optionally, any team member) checks that the PR is well-formatted. If it does not fit the following criteria, they will ask that it is fixed:
    1. the PR is in its own branch
    2. the PR is submitted to develop
    3. the PR only has commits specific to the relevant issue
    4. the PR has necessary information in the description, including how it was tested and how others can test it.
    5. if the PR content is such that a changelog entry is necessary, make sure any relevant information has been added to CHANGELOG.md.
  5. Other team members start PR-specific discussion. Discussion at this point is comprised of:
    1. reviewing the code for any obvious problems
    2. providing feedback about personal experience with this topic
    3. testing relevant examples on untested platforms
    4. thoroughly stepping through the changes to understand potential side effects
    5. examining discrepancies between the original issue(s) and the actual PR
    6. @summoning any relevant team members
  6. Anyone who takes time to do any of the above can offer their assessment. Note that this should not be the time to decide whether the PR is desired or not -- that should have happened earlier. The only condition where a PR should be completely rejected is when it has not gone through the entire process (e.g., someone submitted the PR without posting an issue). The assessment may be one of the following, coupled with a note about which of the above types of review were carried out (e.g., some people might just run an example, others might do more thorough testing):
    1. good to merge
    2. good to merge with minor changes (which are specified)
    3. not good to merge without major changes (which are specified)
  7. If there are more than a certain number of votes (N) saying "good to merge", with at least one of them being a thorough code review, then a Core member is @summoned to execute the merge.
  8. If the PR is not merged within a certain number of days (M) without feedback from the Core, the relevant section leader may execute the merge. This can be stopped at any time by a single constructive vote against merging ("Don't merge this, until you change...") but not by a non-constructive vote ("Don't merge this, I haven't had a chance to look at it yet...").