Skip to main content

13  Peer Review And Revision

13.1 Why This Week Matters

On Monday, November 30, you open a classmate’s project the way a stranger would: a fresh copy from GitHub, nothing on your laptop but what they pushed. You render it, read it, and write a review as a GitHub Issue on their repository. Someone else does the same to yours.

Two things make this worth a class meeting. First, a fresh clone is the honest test of reproducibility: if the report does not render for your reviewer, it will not render for your committee, your agency, or you in two years. Second, reading someone else’s analysis closely is how you learn to see the gaps in your own. A reviewer who writes “where, what I saw, why it matters, what to try” is giving the author something they can act on in a day.

This chapter has three parts:

  1. Give the review (in class Mon Nov 30, filed by Wed Dec 2).
  2. Respond to the review you received (revision workshop Mon Dec 7, finished by Sun Dec 13).
  3. Tag v1.0 on your final commit (by Wed Dec 16, 11:59 PM).
Date Where What
Sun Nov 29, 11:59 PM Home Draft due. Your reviewer starts from what is pushed
Mon Nov 30 Class Clone your reviewee’s repo, render it, write and file the review Issue
Wed Dec 2, 11:59 PM Home Review Issue filed (if not finished in class); Issue URL on Canvas
Mon Dec 7 Class (last class) Revision workshop: answer each comment, fix, commit with refs #1
Sun Dec 13, 11:59 PM Home Every comment answered on the Issue; Issue closed by a commit
Wed Dec 16, 11:59 PM Home Final due: final push plus a v1.0 tag

13.2 Learning Goals

By the end of this chapter, you should be able to:

  • clone a repository you were invited to and test whether it renders without your help
  • write a review comment an author can act on: where, what you saw, why it matters, and a suggestion
  • answer a review point by point, changing what you agree with and declining what you do not, with a reason
  • link a commit to an Issue with refs #1, close it with closes #1, and mark your final commit with a v1.0 tag

13.3 Vocabulary

Term Meaning
Reviewee / reviewer You review one person (your reviewee). A different person reviews you (your reviewer). The list is on Canvas
Fresh clone A new copy of the repository from GitHub, in a new folder, with nothing from your own laptop mixed in
Issue A numbered discussion thread on a GitHub repository. Your review is one Issue; its number (usually #1) appears next to its title
refs #1 Text in a commit message that links the commit to Issue #1, so the Issue shows the commit
closes #1 Text in a commit message that closes Issue #1 when the commit reaches main on GitHub
Commit hash The short ID of a commit, like a1b2c3d. Quote it in your reply so the reviewer can see exactly what changed
Tag A permanent name on one commit. v1.0 marks the commit you submit as your final

13.4 Part 1: Give The Review (Nov 30)

13.4.1 Step 1: Check your access

Open your reviewee’s repository page on github.com (the address is in the reviewer list on Canvas, or ask them). If you see a 404, you have not accepted their invitation. Accept it at your GitHub notifications page or from the invitation email, then reload. No invitation there? Ask your reviewee to check Settings > Collaborators and send it again.

13.4.2 Step 2: Clone it fresh

Clone into a new folder outside your own project and outside any course folder, for example Desktop/review. Do not reuse an old copy.

  • GitHub Desktop: File > Clone Repository, GitHub.com tab, pick your reviewee’s repository (or use the URL tab and paste its address), set Local path to the new folder, select Clone. Then open that folder in Positron.
  • Positron: on the repository page, select Code and copy the HTTPS address. In Positron, New Folder from Git, paste the address, choose the new folder.
WarningYou can push to their repository. Do not.

Collaborators can push, so GitHub will not stop you. Rendering changes report.html in your copy, and GitHub Desktop or Positron will offer to commit it. Do not commit or push anything in the review folder. The Issue is the whole review.

13.4.3 Step 3: Render it

  1. Open the folder (or the .Rproj) so here() finds the right root.
  2. Restart R (Positron: restart the R session; RStudio: Session > Restart R).
  3. Open report.qmd and select Render. Do not edit any file.

If it fails:

  • there is no package called 'x': install it with install.packages("x") (that changes your laptop, not their repository) and render again. Write the package in the Issue under “Packages I had to install”; the README should have listed it.
  • Any other error: copy the exact error message into the Issue. Then keep reviewing: open the author’s own report.html from the folder in a browser and read that alongside report.qmd.
  • The data is not in the repository and the README says it cannot be shared: the author gives you the file privately. Put it in data/raw/. If the README says nothing, that is your first comment.

13.4.4 Step 4: Write the review

Read the rendered report and report.qmd side by side and fill in the template below. Write it in a text file on your laptop first if you like; GitHub does not save a half-written Issue if the tab closes.

## Reproducibility check
- [ ] Cloned fresh and opened the .Rproj
- [ ] Report rendered with no edits (if not, exact error below)
- [ ] Raw data present in data/raw/
- [ ] No absolute paths or setwd()
- [ ] README explains how to render

Packages I had to install:

Render error (if any):

## Checklist spot-check
Mark each: present / missing / unclear
- Import and inspect:
- Clean (names, types, validation, NA decision):
- Transform (summary, reshape or join, row counts):
- Figures (3+, captions describe patterns, units):
- Table and inline value:
- Beyond the course + "What I explored" note:

## Comments
At least three. At least one on data cleaning decisions, one on a figure,
one on the interpretation.

### 1.
- **Where:**
- **What I saw:**
- **Why it matters:**
- **Suggestion or question:**

### 2.
- **Where:**
- **What I saw:**
- **Why it matters:**
- **Suggestion or question:**

### 3.
- **Where:**
- **What I saw:**
- **Why it matters:**
- **Suggestion or question:**

## One thing that works well
(specific: where and why)

## One question about the science

## Top priority
The one change that would most improve this project:

The checklist spot-check uses the final report checklist in Your Project Repository. This is a draft, so “missing” is expected in places. Mark it honestly; the author needs to know before Dec 16, not after.

13.4.5 What a useful comment looks like

A comment the author can act on has four parts: a place they can find, an observation they can check, a reason it matters, and a way forward. Compare:

Weak What is missing
This looks wrong. Where? What looks wrong? The author cannot find or check it
Figure 2 is confusing. Confusing how? Which part? No way forward
Rewrite the cleaning section. No reason and no specific change; too big to act on
Great job! Pleasant, and tells the author nothing to keep or change

A strong comment on a cleaning decision:

13.4.6 1.

  • Where: Data and Methods, chunk clean-depth
  • What I saw: filter(depth_m > 0) drops rows, and the row count goes from 1,204 to 1,150 with no sentence about it.
  • Why it matters: a reader cannot tell whether the 54 dropped rows were recording errors or real samples at zero depth. If they are real, dropping them raises the mean depth.
  • Suggestion or question: say in Methods how many rows were dropped and why. If zero depth is possible at these sites, keep them.

A strong comment on a figure:

13.4.7 2.

  • Where: Results, the catch-by-season figure (chunk fig-cpue-season)
  • What I saw: the y axis says cpue with no units, and the caption says “CPUE by season” without saying what the figure shows.
  • Why it matters: fish per hour and fish per net-night differ by an order of magnitude, and the caption is the first thing a reader looks at.
  • Suggestion or question: label the axis with units and make the caption state the pattern, for example “Catch rates were highest in spring at all three reservoirs.”

A strong comment on the interpretation:

13.4.8 3.

  • Where: Interpretation, second paragraph
  • What I saw: “Grazing caused the decline in grass cover.” The data compare grazed and ungrazed pastures in one year.
  • Why it matters: a one-year comparison shows a difference, not its cause; pastures may have differed before grazing started.
  • Suggestion or question: “Grass cover was lower in grazed pastures” says what the data show. Is there pre-grazing data you could add?

Keep the tone to the work, not the person: “the row count drops without explanation”, not “you forgot to explain”. Questions are fine when you genuinely do not know (“Are zero depths possible at these sites?”).

13.4.9 Step 5: File the Issue

  1. On your reviewee’s repository page on github.com, select Issues > New issue.
  2. Title: Peer review: <your name>.
  3. Paste your filled-in template into the description. Select Preview to check that headings and checkboxes look right.
  4. Select Create (or Submit new issue).
  5. Copy the Issue’s address from your browser (it ends in /issues/1 or similar) and submit it on the Canvas assignment Peer Review: Giving.

When it is filed, delete the review folder from your laptop.

13.5 Part 2: Respond To Your Review (Dec 7, Done By Dec 13)

Your review arrives as an Issue on your repository. GitHub emails you; you can also find it under Issues on your repository page.

  1. Read the whole Issue before changing anything. Fix the reproducibility problems first: a report that does not render for your reviewer will not render for the instructor.

  2. Decide on each numbered comment: change it, or decline it with a reason. Declining is fine when you have a reason (“the 2019 drought year stays in: it is the event the question is about”).

  3. Fix one comment per commit where you can, and put refs #1 in the commit message (use your Issue’s number). GitHub then lists the commit on the Issue.

    • Positron: in Source Control, stage the files, type a message such as Explain why 54 zero-depth rows were dropped (refs #1), select Commit, then Sync.
    • GitHub Desktop: check the files, type the same message in Summary, select Commit to main, then Push origin.

  4. Reply on the Issue with one line per comment. Find each commit’s short hash in GitHub Desktop’s History tab, Positron’s Source Control graph, or on the Issue itself where GitHub listed the commit.

    1. Changed in a1b2c3d: Methods now says 54 rows had depth 0 and why they were dropped.
2. Changed in e4f5a6b: axis now "Catch per net-night", caption states the pattern.
3. Declined: the 2019 drought year stays in; it is the event the question is about. Explained in Methods.

  5. Close the Issue with your last revision commit: put closes #1 in its message, for example Add units to discharge axis (closes #1). When you push, GitHub closes the Issue and links the commit. Do not close it with the button: the closing commit is part of the grade.

Your reviewer does not need to reply. If they do, answer them on the Issue.

13.6 Part 3: Tag v1.0 (By Dec 16)

When your report is finished, pushed, and renders from a fresh clone, put a tag named v1.0 on that commit. The instructor grades the commit your latest tag points to. No tag by the deadline means not submitted.

Pick one route.

GitHub website (works for everyone):

  1. On your repository page, select Releases (right side) > Draft a new release (or Create a new release).
  2. Choose a tag: type v1.0, then select Create new tag: v1.0 on publish. Target: main.
  3. Title: Final submission. Select Publish release.

GitHub Desktop:

  1. Push everything first (Push origin).
  2. History tab, right-click your newest commit, Create Tag…, type v1.0, select Create Tag.
  3. Select Push origin again to send the tag.

Terminal (Positron’s Terminal, in your project folder):

git tag -a v1.0 -m "Final submission"
git push origin v1.0

Whichever route you use, check on github.com: your repository page should show 1 tag (or Tags) near the branch menu, and v1.0 should point to your last commit.

Fixed something after tagging? Push the fix and tag it v1.1 before the deadline. The latest tag is the one graded.

13.7 Common Problems

You see What it means Fix
404 on your reviewee’s repository You have not accepted their invitation Accept at github.com/notifications; if none is there, they re-send it
Clone asks for a password, or fails with Authentication failed Git on this laptop is not signed in as you Clone with GitHub Desktop instead (it uses your Desktop sign-in)
there is no package called The author uses a package you do not have install.packages() it, render again, note it in the Issue
cannot open file / does not exist Data not committed, or an absolute path Copy the exact error into the Issue; review from the author’s report.html
Desktop shows changed files in the review folder Rendering rewrote report.html Ignore them. Do not commit. Delete the folder when done
refs #1 did not link the commit Wrong number, or the commit is not pushed yet Check the Issue number; push
Issue did not close after closes #1 The commit is not on main on GitHub yet Push. It closes when GitHub sees the commit on main
Tag made but not on GitHub Tags are pushed separately Desktop: Push origin. Terminal: git push origin v1.0

13.8 Try It

Before Nov 30, do Part 1, Steps 2 and 3 on your own repository: clone it fresh into a new folder and render it. Whatever breaks for you there will break for your reviewer on Monday. Fix it in your original folder, push, and delete the test folder.

13.9 Connect To The Assignment

The Peer Review is worth 100 points, in two Canvas assignments. Your reviewer never grades you: you are graded on the review you give and on how you respond to the one you get.

Part Criterion Points
Giving (due Wed Dec 2) Reproducibility check done with evidence: fresh clone, render result, exact error if any 15
Checklist spot-check completed honestly 10
Three or more comments with Where / What I saw / Why it matters / Suggestion, covering cleaning, a figure, and the interpretation 25
A specific strength, a science question, a top priority; professional tone; filed by Dec 2 10
Responding (due Sun Dec 13) Every numbered comment answered on the Issue (changed or declined) 15
Changes traceable: commits reference the Issue; the Issue is closed by a commit 15
Declines have reasons; replies are professional; done by Dec 13 10

If your reviewer never files, you are not penalized: the instructor files a review and you respond to it as normal.

The review also feeds your final report grade indirectly. Before grading, the instructor reads your review Issue and checks that each problem your reviewer found was fixed or reasonably declined.

13.10 Finish The Professional Workflow