Reviewing a lecture
Reading a review pull request
Each lecture comes to you as a pull request in your edition's repository. This page explains what you find on it, which parts to read and which parts you can skip.
What a review pull request is
A pull request proposes a change to a repository. A review pull request adds one lecture to your edition: a draft that @mmcky made with the latest release of action-translation. You review the draft on the pull request. When the pull request is merged, the lecture becomes part of the edition.
The title names the lecture and the release of the engine that drafted it. The description starts by naming the lecture's review issue. GitHub closes the issue when the pull request is merged.
The description, section by section
The description is written for you. Its sections usually come in the order below, although their headings vary a little. The first section, for example, can be called “For the reviewer” or “For the translator”. For a live example, see the Malayalam review pull request for the pandas lecture.
| Section | What it holds | What you do |
|---|---|---|
| For the reviewer | What we ask of you in this round | Read it first. |
| New since the last draft | What the last review changed in the engine, and where those changes show in this lecture | Check that those lines read well. |
| Provenance | Technical details of how the draft was made | Skip it. |
| Machine verification | What scripts checked against the English, such as the number and order of headings and code cells | Skip it. |
| Left as generated for you to call | Lines we were unsure of, left as the engine wrote them | Decide each one. |
| Disclosures | How this draft was chosen, and each change a script made to the text | Check the lines a script changed. |
New since the last draft
This section shows what the last review taught the engine. It names each change and the lines of this lecture where the change shows, or it says that the change did not arise in this lecture. For the first lecture you review, it says instead which terminology and house-style rulings the engine already carries.
Left as generated for you to call
“To call” here means “to decide”. Our checks sometimes find a line we are unsure of. We leave that line as the engine wrote it and list it here, with its line number and what we noticed. Read each listed line and decide. If you would change it, suggest the change as you would for any other line.
Disclosures
The first part says how this draft was chosen. You can skip it. The second part lists every change that a script made to the text after the engine wrote it, by line number. If a line changed by a script reads wrong to you, flag it like any other line. That tells us the script is wrong. A last part may say how AI was used to make the draft and write the description. That is our own disclosure, and it asks nothing of you.
The preview
A bot posts a comment on the pull request with a link to a preview of the rendered lecture. Read the whole lecture there, as readers will see it, with the maths and formatting in place. The preview is rebuilt when the pull request changes, and the bot posts a new comment each time.
The Files changed tab
The Files changed tab shows the source of the lecture: plain text with formatting marks, written in Markdown. This is where you make your suggestions. A review pull request adds the whole lecture, so every line appears there as new. See Reviewing on GitHub.
Review the lecture file, in the lectures folder. If the pull request changes any other file, you can skip it, unless the description asks you to review it.
The block at the top of the file
Each lecture file starts with a block of settings between two lines of three dashes (---). One part of the block starts with translation:. It holds the title of the lecture and a heading map, which the engine uses to match each section of the translation with its section in the English.
Skip the whole block. If you change a heading in the lecture, @mmcky updates the heading map for you.
Automated reviews
GitHub Copilot may leave an automated review on the pull request. It needs no attention from you, and neither does any other automated review. Copilot does not know your edition's house style, and @mmcky answers its comments. If you agree with something it says, write your own comment in your own words. Your comment is the one that counts.
The draft is not edited by hand
Nobody edits the draft by hand before you see it. The engine wrote every line, apart from the script changes listed under the disclosures. So each correction you make shows exactly where the engine made a mistake, and the engine can learn from it. See How your review is used.