Review The Docs

Review docs PRs

Local review workflow for supabase/supabase docs changes. Classify first, then follow the matching checklist.

Two modes:

• Open PR review (default) — triage via gh, checkout, verify, report. Start at Phase 1.
• Local self-review — no open PR yet; verify the current branch before opening one. Start at Local self-review.

For implementing docs fixes (Linear tickets, worktrees, platform E2E), use work-linear-issue instead.

Core rules

1. Classify before reviewing — path patterns determine which checklist applies.
2. Review stacked PRs bottom-up — each PR may base on the previous branch.
3. Run verification locally — do not approve from diff alone.
4. Compare against master when the PR claims to fix missing or broken output.
5. One report per batch — sequential review, consolidated output at the end.
6. Separate blockers from nits — type/style notes are suggestions unless output breaks.

Repository layout

Local self-review (no open PR)

Use this on your own branch before opening a PR (checklist Stage 4). No gh pr required.

cd <your supabase/supabase checkout>
# Ensure you're on the feature branch, not master
git branch --show-current
git diff --name-only master...HEAD

1. Classify from git diff --name-only master...HEAD using the Phase 2 table.
2. Walk the bar in pm-the-docs's checklist — "What good looks like" and the Self-review checkboxes.
3. Run type-specific checks from the matching sections below on the current branch (no checkout step). Typical commands:

# Pipeline / schema handler
cd apps/docs && pnpm build:guides-markdown
# inspect public/markdown/guides/ for affected pages
pnpm build:reference-markdown   # when reference pipeline changed

4. Spot-check frontmatter, internal links, and nav wiring for content changes.
5. Offer runnable verification — for content/tutorial PRs with new or changed procedural fenced blocks, ask whether to run test-the-docs. Prerequisites are class-specific (Docker Compose stack profile for DB/API; examples profile for example-app). If accepted, include the verification report; if declined or a required prerequisite for that class is missing, record credible deferred reasons for those artifacts only. Do not reimplement sandbox execution here.
6. Write a short self-review note (blockers vs nits) suitable to paste into the future PR body under a "Self-review" heading.

Then open the PR and continue with open-PR review if a second pass is needed.

Phase 1 — Triage (read-only)

List PRs

Filter by author, label, or list all open docs PRs:

# By author
gh pr list --repo supabase/supabase --author <github-user> --state open \
  --json number,title,url,reviewDecision,latestReviews,changedFiles,additions,deletions,labels

# All open docs-labeled PRs
gh pr list --repo supabase/supabase --state open --label documentation \
  --json number,title,url,reviewDecision,latestReviews,author,changedFiles

PRs with empty reviewDecision and no APPROVED review need approval.

Map the stack

gh pr view <number> --repo supabase/supabase \
  --json number,title,baseRefName,headRefName,body,files

Stacked series: master → PR A → PR B → PR C. Review and merge bottom-up.

Phase 2 — Classify PR type

Inspect changed files from gh pr view or:

gh pr diff <number> --repo supabase/supabase --name-only

When a PR spans types (e.g. schema handler + component refactor), run all matching sections.

Phase 3 — Sequential local review

Repeat for each PR (bottom of stack first).

Common steps (all PR types)

Checkout and install:

cd <your supabase/supabase checkout>
gh pr checkout <number> --repo supabase/supabase
pnpm install --filter docs...   # when node_modules missing or deps changed

CI spot-check:

gh pr checks <number> --repo supabase/supabase

Baseline on master (when PR fixes missing/broken output):

git checkout master
# run type-specific verify command (see sections below)
git checkout -   # return to PR branch

Schema handler review

For PRs adding static markdown fallbacks for React MDX components.

Code checks — each handler in apps/docs/internals/markdown-schema/:

Find usages: rg '<ComponentName' apps/docs/content/

Build and inspect:

cd apps/docs && pnpm build:guides-markdown
# Expect: "Generated N markdown files" where N roughly matches the .mdx count under content/guides/

Inspect public/markdown/guides/ for affected pages:

• Previously blank sections now have lists, tables, or links
• All MDX pages using the component are covered, not just the one in the PR description
• Link format: /docs/guides/... locally; absolute URLs when VERCEL_ENV=production

Pipeline review

For AST refactors, link rewriting, reference markdown generation, etc.

cd apps/docs
pnpm build:guides-markdown
pnpm build:reference-markdown   # when reference pipeline changed
pnpm test:local:unwatch internals/internal-links.test.ts   # when link handling changed (needs local Supabase — see apps/docs/AGENTS.md)

Verify both guides and reference output when generate-reference-markdown.ts or internal-links.ts changed.

Content review

MDX prose, partials, navigation — no pipeline or example changes.

Check the prose against the style guide yourself. No CI or local check covers style or terminology. CodeRabbit reviews style, terminology, and structure on apps/docs/content/**/*.mdx, but only once the PR is open.

Check WORD_LIST.md against the finished page last, using the two-pass protocol in Use with an AI agent: Phrase groups for the literal term lists, then grep '^### ' WORD_LIST.md and read only the entries matching words on the page. Include terms the author didn't introduce.

Checklist:

• Voice follows 01-voice-and-tone.md
• Section grouping and chunking follow 03-page-structure.md
• Components follow 02-elements.md
• Terminology matches WORD_LIST.md
• Frontmatter valid (title, description where required)
• Internal links resolve (/docs/guides/..., not broken anchors)
• $CodeSample paths match existing example directories
• Admonitions, tabs, and partial includes render sensibly in PR preview
• No accidental whitespace-only or empty sections where components were removed
• Offered test-the-docs for new/changed procedural snippets; verification report present or credible deferred reasons recorded

Compare PR preview URL (from Vercel/deployment comment) against production for visual regressions when layout components are involved.