Reviewing a lecture

Reviewing on GitHub

You review a lecture on its pull request, in your web browser. This page shows how to suggest a change to a line, how to commit a larger change instead, how to keep your work across several sittings, and how to approve the pull request when you finish.

Last updated

Before you start

Sign in to GitHub and open the review pull request. Read the whole lecture in the preview first, then make your suggestions on the pull request. See Reading a review pull request.

Suggest changes, step by step

  1. Open Files changed. On the pull request, click the Files changed tab. It shows the lecture file line by line.
  2. Choose a line. Hover over the line you want to change, and click the blue + icon that appears beside it. To change several lines together, click the blue + beside the first line and drag down to the last one.
  3. Insert a suggestion. In the comment box that opens, click the Insert a suggestion button. Its icon shows a plus and a minus sign. You can also press Ctrl+G, or Command+G on a Mac. GitHub copies the line into the box between two marker lines. Change the text between the markers so that it reads as you want it.
  4. Start a review. Click Start a review. For each later suggestion, click Add review comment. Your comments are now pending: only you can see them, and you can edit them, until you submit the review. They stay saved, so you can stop and continue on another day.
  5. Approve and notify @mmcky. When you have finished the whole lecture, click Submit review, above the changed lines. On some screens this button is called Review changes. Write a one-line summary that mentions @mmcky, for example: “Review complete. @mmcky, this is ready to merge.” Choose Approve, then click Submit review.
Before ```suggestion The draft's line ``` Added by GitHub You edit After ```suggestion Your corrected line ``` Markers unchanged
When you click Insert a suggestion, GitHub copies the line into the comment box, between a marker line that reads ```suggestion and a closing marker line, ```. Replace the text between the markers with your version. Leave the two marker lines as they are.

Approving

Choose Approve even when you have made many suggestions. On a review pull request, your approval means that your review is complete. @mmcky then applies your suggestions and merges the pull request. See After your review.

One suggestion for each line

Make a separate suggestion for each line you would change. Select several lines only when one change covers them all.

Use a plain comment, with no suggestion in it, for a question, for something a suggestion cannot express, or for a pattern that appears throughout the lecture. Write it on the line it concerns, in the same way, without inserting a suggestion. For a remark about the whole lecture, write it in your summary when you submit, or on the Conversation tab.

Keep the formatting marks

The lecture file is written in Markdown, which uses ordinary characters as formatting marks. Keep each mark in your suggestion, in its place in the line:

  • backticks around code, as in `numpy`;
  • asterisks around words in italics, as in *prefer*;
  • square brackets and parentheses around a link, as in [link text](https://…);
  • dollar signs around maths, as in $x^2$.

If you are unsure whether something is a mark, keep it as it is. If a mark goes missing from a suggestion, @mmcky restores it in a separate commit and asks you to check it.

Or commit your changes

Suggestions are the usual way to review. You can also edit the lecture file directly and commit your change to the pull request's branch. A commit suits a larger change, such as rewriting a paragraph, splitting or joining sentences across lines, or many changes close together. It also keeps every formatting mark exactly as you typed it.

  1. Open the file in the editor. On the Files changed tab, click the ⋯ menu at the top right of the lecture file, then Edit file. The file opens in GitHub's editor, on the pull request's branch.
  2. Make your changes. Keep the formatting marks, as for a suggestion.
  3. Commit. Click Commit changes. Write a short description of what you changed, keep Commit directly to the branch selected, and click Commit changes again.

Your commit appears on the pull request under your name, and the preview updates. You can mix commits and suggestions in one review. When you have finished, approve the pull request and notify @mmcky, as for suggestions. A committed change that is not kept gets a reply on the pull request, saying why.

Commit only on review pull requests. On a sync pull request, automation can rewrite the branch, and your commit could be lost.

Read the whole lecture in the preview

Files changed shows only the lines that a pull request changes. On a review pull request that adds a whole lecture, that is every line. On a pull request that changes a lecture already in your edition, the unchanged lines are hidden. So read the whole lecture in the preview as well. If you see a problem there, find the same line under Files changed and suggest the change on it.

GitHub's guides

GitHub's own guides show each step with screenshots:

These guides also describe Copilot features in GitHub. Do not use Copilot features for your review. See Review by hand.