Procedure for peer review

In this course each assignment is reviewed by two other colleagues. This implies that you need to review two assignments each week. To arrange this we are going to use the pull requests feature from GitHub. This pull request is where the reviewers place their comments.

Owner of the repo

GitHub classrooms should have automatically created a pull request on the repository called “Feedback” for you. If not, you will need to create a pull request from the empty branch into the master branch. These are the steps to do so:

  1. Go to your repo.
  2. Click the New pull request button.
  3. In the next screen, select empty as your base branch, and master as your compare branch.
  4. Give it name similar to “Feedback”.

Reviewers

GitHub classrooms will have automatically created a pull request on the repository called “Feedback” (or the owner will do this manually). Each reviewer should place their comments in that pull request. To find it:

  1. Go to the repo you need to review
  2. Click on the Pull requests tab
  3. There you should find the PR titled “Feedback”; click on it

We expect you to do two kinds of reviewing:

  1. General comments about the design and implementation, which should be in the Conversation tab.

  2. An in-depth review of the code. To do this, go to the Files changed tab and select the Unified view. You can place a comment in one line by clicking on the small plus sign which appears when you place your mouse over the line number.

Owners of the repo can reply to those comments, and engage in conversation.

Once your review is finished, send an e-mail to w.s.swierstra@uu.nl with the grades of the two colleagues you reviewed. Include a link to the two repositories you reviewed in your email so that we can go to it directly. You do not need to leave the grade you assign in the feedback/comments itself. As with the assignments themselves, the peer reviews are due after one week.

How to write a good review

The main rule is to be constructive. This means that for every issue you find:

  1. Be clear about which is the problem;
  2. Explain or point to a possible solution. It is better to suggest improvements to the current code than a whole new approach;
  3. Distinguish clearly between “I would have done this differently” from “this is wrong or this does not work”;
  4. Raise questions about unclear parts.

Needless to say, be respectful about your colleagues’ work.

You will be graded on the quality of the feedback given.