Skip to main content

Review checklist

Review happens in this order. Each gate is cheaper than the one after it, so a pull request that fails gate 1 is not read for gate 4.

Self-review against this list before requesting review. It is the fastest path to a merge.

Gate 1 — Automated​

Nothing below is checked by a human. If CI is red, fix it first.

  • pnpm validate passes — frontmatter, structure, assets, internal links
  • pnpm lint passes — Markdown, spelling, formatting, JavaScript
  • pnpm build passes — no broken cross-references, no MDX errors
  • Commit messages follow Conventional Commits
  • The pull request template is filled in, not deleted

Gate 2 — Correctness​

The only gate where being wrong is worse than being unclear.

  • Every command was actually run, on a current Git release, in a clean repository
  • All output is verbatim, not reconstructed from memory
  • Version-dependent behaviour is marked with <VersionNote> and the version is correct
  • Destructive commands carry a warning proportionate to the damage
  • Terminology matches the style guide — especially index, remote-tracking branch, object ID
  • Nothing contradicts an existing lesson. If it does, say so in the pull request and fix both

Gate 3 — Pedagogy​

  • Objectives are observable capabilities, not "understand X"
  • The concept is explained before the first command
  • Prerequisites are complete — nothing is used that has not been taught or linked
  • Checkpoints exist wherever silent divergence would break later steps
  • At least one exercise, with progressive hints and a worked solution
  • Quiz options each carry an explanation, including the correct one
  • The failure modes section covers what actually goes wrong here

Gate 4 — Structure and style​

  • The eight-part lesson skeleton is present and in order
  • Heading levels descend without gaps; nothing deeper than H4
  • 700–1,600 words; over 2,200 needs justification or a split
  • No "simply", "just", "easy", "obviously"
  • Second person, present tense, active voice
  • Placeholders use <kebab-case-in-angle-brackets>
  • Link text stands alone out of context

Gate 5 — Assets and accessibility​

  • Every image has meaningful alt text; decorative images have alt=""
  • Diagrams are Mermaid or <GitGraph> unless there is a stated reason
  • Images are under 400 KB and correctly located
  • No colour-only encoding of meaning
  • Every <GitGraph> has a caption
  • Tables have header rows and are not used for layout

Gate 6 — Integration​

  • sidebar_position places the document sensibly among its siblings
  • The module overview links to it (pnpm content:toc <module>)
  • Related lessons link to it where a reader would expect them to
  • New terminology is added to src/data/glossary.ts and the glossary module
  • Any URL change has a matching entry in src/data/redirects.ts
  • New tooling words are added to .cspell/project-terms.txt

For reviewers​

Comment on the writing, not the writer. "This paragraph assumes the reader knows what a refspec is" — not "you assumed too much".

Distinguish blocking from optional. Prefix non-blocking comments with nit:. A reviewer who blocks on preferences trains authors to stop contributing.

Verify at least one command yourself. Reviewing prose is easy; reviewing correctness requires running something. Pick the most consequential command in the pull request and run it.

Two approvals are required for new lessons, one for corrections and typographical fixes. See CODEOWNERS for who is routed what.