Reviewing a lecture

How a review round works

During the initial translation of an edition, you review one lecture at a time. Each lecture is one round: we draft it, you review it, and we improve the translation engine from your review before the next lecture is drafted.

Last updated

One lecture at a time

A round covers a single lecture. The pull request for your next lecture opens only after this one has been merged and the engine has learned from your review.

Working this way means each new draft starts from everything your earlier reviews taught the engine. Each lecture should then need fewer corrections than the one before.

next round 1 Draft the lecture @mmcky opens a pull request 2 Review the lecture You suggest changes 3 Approve and notify You mention @mmcky 4 Apply and merge @mmcky credits you 5 Answer questions on a follow-up issue 6 Improve the engine Checked against your version 7 Next lecture From the improved engine
One round, numbered as in the steps below. The shaded steps are yours; the others are done by @mmcky. Step 5 happens only when your review raises a question, which is why its path is dashed.

The steps

  1. We draft the lecture. @mmcky drafts the lecture with the latest release of the translation engine and opens a pull request in your edition's repository. The description says what changed since your last review, how the draft was made and what was left for you to decide. A link to a preview of the rendered page appears on the pull request. See Reading a review pull request.
  2. You review the whole lecture. Read the lecture in the preview, then suggest your changes on the pull request, one suggestion for each line you would change. For a larger change, you can commit it to the pull request instead. Use a comment for anything a suggestion cannot express. See Reviewing on GitHub and What to look for.
  3. You approve the pull request and notify @mmcky. When your review is complete, submit it with Approve and mention @mmcky in the summary, for example: “Review complete. @mmcky, this is ready to merge.” Your approval is the signal that the lecture is ready.
  4. We apply your suggestions and merge. @mmcky applies your suggestions as you wrote them, with you credited as co-author, and replies to any suggestion that was not applied. Changes you committed are already on the pull request, under your name. Any other change is made in a separate commit and listed for you to check. @mmcky then merges the pull request, which closes the lecture's review issue.
  5. You answer any follow-up questions. If your review raises a question, for example about a term that appears in other lectures, it is posted as an issue in the edition's repository for you to answer. See After your review.
  6. We improve the engine and check it against your version. Your corrections become glossary entries, rules or automatic checks in the engine. We then translate the lecture again with the improved engine and compare the result with your merged version, to confirm that the improvements work.
  7. The next lecture's pull request opens. It is drafted with the improved engine, and its description lists what changed because of your review.

Timing

There is no deadline for a review. Take the time you need to read the whole lecture carefully.

Between rounds there is a gap while the engine is improved and checked, so the next pull request may take some days to appear. If you note on the pull request roughly how long your review took, it helps us plan. This is optional.

During development and later

These steps describe the initial translation of an edition, while the engine is still being improved from each review. In this phase you approve and @mmcky merges, because each merge is tied to a change in the engine.

Once an edition is complete and runs on a stable release of the engine, editors will approve and merge pull requests themselves. A different process will then apply to the sync pull requests that carry later changes from the English lectures. See Sync reviews.