CSE 403 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 and your team: 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, then build the project and run its tests.

Read the user documentation, then run the project.

Open issues with your comments and questions. If you are blocked (that is, you encounter unexpected behavior when building/testing/running the reviewed system and you cannot proceed), clearly indicate that in your pull request title and text. If another team opens a blocking issue on your repository, resolve it immediately.

You may open a pull request with suggested improvements if you see how to resolve an issue that you raised, but this is not required.

2. Write and submit a review

You will submit a single text document, consisting of a checklist and a list of URLs.

Review checklist (50%)

Start with the two checklists below; for any item that you cannot check, include 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 enough that I could follow them.

  • 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.

  • The instructions for how to add a new test case are clear enough that I could follow them.

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%)

Open issues with high-level feedback and constructive criticism focusing on their implementation, descriptive writing, or technical setup. Each issue should only address one concern.

In addition, open one issue with praise: point out aspects of their project that you appreciated or found to be well-done. (This is customary in a pull request, but you are not reviewing a pull request, and we wanted to provide a place for the praise.)

What to submit

Submit, to Canvas, a text file containing the checklist and issues or pull requests. Each issues or pull request should be given as

  • Issue or pull request title
  • URL

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?

Still open an issue on GitHub, explaining why the instructions are insufficient.

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

Pull requests are optional. If you choose to make a pull request, here are instructions:

  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. Create a branch in the forked repository.

  6. Make changes in the branch, then push them.

  7. Open a pull request on GitHub into the original repository.

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