Course project: Peer review

Overview

Peer-review another team’s project and provide suggestions for improvements. This helps the other team by providing a fresh perspective and giving them outside feedback. It also helps you: you will see how another team is approaching a problem, which can give you ideas of what to do or what to avoid.

Setup

INDIVIDUALLY peer-review the project assigned to you for review. To find the project to review, open this milestone assignment in Canvas and find the project name associated with your name in the table.

Instructions

1. Review your assigned project and file issues for any encountered problems

Read the developer guidelines, user documentation, then build, test and run the project.

If you encounter unexpected behavior when building/testing/running the reviewed system that prevents you from proceeding, open an issue – following the instructions described in the system’s repository.

You may also provide a pull request with suggested improvements if you see how to resolve an issue that you raised.

2. Write and submit a review

Produce a single PDF document with your review consisting of two parts.

Review checklist (50%)

Start with the two checklists below; for any item that you cannot check, include either a comment for the team explaining why, or a link to the relevant issue you opened in their repository.

Developer guidelines

• There are developer guidelines, which I could easily find in the repository.

• The developer guidelines are self-contained and well structured.

• The description of the repository structure is clear and makes sense to me.

• The instructions for how to add a new test case are clear and make sense to me.

• I could build the software, following the provided instructions, on a machine matching the prerequisites mentioned in the instructions.

• I could test the software, following the provided instructions.

• The continuous integration (CI) setup makes sense to me, and I could find the build history.

User manual

• There is a user manual, which I could easily find in the repository.

• The high-level description of the system is clear.

• The user manual is self-contained, well structured, and comprehensive.

• The user manual contains all instructions required to use the system.

• I could install the software, following the provided instructions.

• I could run the software, following the provided instructions.

• I could use the software, executing the functionality described in the manual.

• The instructions for filing a bug report are clear and sufficient.

Feedback (50%)

After completing the checklist, include a section of high-level feedback and constructive criticism focusing on their implementation, descriptive writing, or technical setup.

Submit this review as a PDF document to Canvas by due date. (Check Calendar!)

Clarifications

What if I need to file an issue but there are no instructions provided for how to do so, or the instructions are unclear?

In this case, still open an issue on GitHub and, additionally, explain why the instructions are insufficient in your review.

How would I provide a pull request to fix an issue?

1. Log into your GitHub account;

2. open the repository of the reviewed system on GitHub;

3. click “Fork”, which will create a clone of the repository under your account;

4. clone the forked repository (under your account) to your computer;

5. make changes and push to your forked repository;

6. open a pull request on GitHub into the original repository.

For each opened issue and pull request, include a reference in your review.