An open source design system that's fully customizable and agent ready
TypeScript
docs(review): document the review gate workflow (#3862)
Cindy Zhang2a541d46ade8
diff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.mdnew file mode 100644index 0000000000..2bbd49f03a--- /dev/null+++ b/.github/REVIEW_GATE.md@@ -0,0 +1,129 @@+# Review gate++How pull requests are gated for review in this repo. The goal: **let the team+move fast in their own domain, require review where risk or unfamiliarity+warrants it, and keep the PR queue readable** (a PR awaiting review shows a+neutral yellow "waiting" signal, not a red failure).++## TL;DR++| Author | High-risk code | Design-affecting change | Everything else |+| --- | --- | --- | --- |+| **Eng owner** (`ENGOWNERS`) | self-serve | advisory label only | self-serve |+| **Design owner** (`DESIGNOWNERS`) | needs code review | self-serve | self-serve |+| **Contributor** (anyone else) | needs code review | needs code review + design label | needs code review |+| **Bot** (Dependabot, etc.) | exempt | exempt | exempt |++- **Code review is the only hard gate.** It shows up as the `review-required`+ status: `pending` (π‘, blocks the merge) or `success` (π’).+- **Design review is advisory** β it labels the PR and requests design owners,+ but does not block the merge.+- An entitled owner's **approval clears the gate automatically** (no manual step).++## Sources of truth++| File | Meaning |+| --- | --- |+| `.github/ENGOWNERS` | Engineering team. Self-serve **code**. |+| `.github/DESIGNOWNERS` | Design team. Self-serve **design**. Checked first. |+| `.github/CODEOWNERS` (`*` line) | Who can **clear** the code gate (and native review requirement). |+| `.github/copilot-instructions.md` + `instructions/*` | Copilot reviewer guidance (advisory). |++Author bucket is resolved in order: **design owner β eng owner β contributor.**+A handle in `DESIGNOWNERS` is treated as a design owner even if also an eng+owner. Anyone in neither file is a contributor (and gets a quiet `community`+label so the contribution queue is filterable).++## What counts as high-risk / design-affecting++Detection is **path-based and deterministic** (no LLM in the enforcement path).+`packages/lab/**` is filtered out entirely first β lab is canary staging, so+new components there are expected and never gate.++**High-risk code** (drives the code gate):+- a new package (`packages/<name>/package.json` added)+- a new component/module in a published `src/` (not lab)+- a runtime change under `packages/core/src/**` (incl. styling `.tsx`; excludes+ tests/docs/stories) β core has high blast radius+- a public API surface change (a `src/**/index.ts(x)` barrel or a+ `package.json`)+- **plus:** *any* PR from a contributor (see policy note below)++**Design-affecting** (drives the advisory design label):+- StyleX styling, theme/token files, template `.tsx`, docsite visual dirs+ (`app`/`components`/`themes`)++**Safe spaces** (never gate): `sandbox`, `storybook`, `lab`.+**Design spaces** (advisory, not blocking): `themes`, `templates`, `docsite`.++## Policy note β contributors++All contributor (non-owner) PRs require code review, not just high-risk ones.+External contributors can't self-merge anyway; this mainly ensures a human on+internal contributors' PRs. Owners still self-serve their own domain.++## The mechanism (two workflows)++```+β PR opened / updated ββpull_request_targetβββΊ review-signal.yml : flag+ bot? β status success, exempt, stop+ resolve author bucket (DESIGNOWNERS β ENGOWNERS β contributor)+ detect high-risk / design from changed paths (lab filtered out)+ read reviews β codeApproved / designApproved+ effective gate = detected/contributor gate AND NOT owner AND NOT approved+ β labels: needs:code-review Β· needs:design-review (advisory) Β· community+ β request reviewers: CODEOWNERS (code) Β· DESIGNOWNERS (design)+ β if code-gated: disable auto-merge+ β set commit status "review-required": pending π‘ (blocks) | success π’+ β neutralize any stale action_required "review-required" check run++β‘ approval ββpull_request_reviewβββΊ review-signal runs a tiny "anchor" job+ so the workflow COMPLETES, which fires:+ βββββββββββββββββββββββββββββββββββββββββββββββ+ β review-clear.yml (workflow_run, base token) β β works for fork PRs+ βββββββββββββββββββββββββββββββββββββββββββββββ+ resolve the PR by the run's head_branch (head_sha points at main here)+ entitled CODEOWNER approved?+ β drop needs:code-review Β· status β success π’ Β· neutralize stale check++β’ branch protection on main+ required status context "review-required": pending blocks, success allows+ + 1 required approving review (native)+ β blocks non-admin merges even for write-access internal contributors+```++## Enforcement++`review-required` is a **required status check** on `main`, plus the native+"1 approving review" requirement. Because a required check blocks non-admin+merges regardless of write access, this holds internal contributors who have+write but are not owners. (Repo admins can still bypass.)++## Why a commit status (not a check run)++The gate is a **commit status**, not a check run, for two reasons:+1. Branch protection requires `review-required` as a **status context**+ ("Expected β waiting for status to be reported"); a check run of the same+ name does not satisfy it.+2. A `pending` status renders as a neutral **yellow** dot ("waiting"), not a red+ failure β so a PR awaiting review does not add red noise to the queue.++PRs gated before this switch may carry a stale `action_required` **check run**;+both workflows neutralize it (a leftover would otherwise drag the status rollup+to failure).++## Recovery / manual re-flag++`review-signal.yml` has a `workflow_dispatch`:+- blank `pr` input β re-flag **all** open PRs (backfill / mass recovery)+- a PR number β re-flag just that one++Use it if a PR's `review-required` ever gets stuck (e.g. the workflow was added+after the PR was opened, or a stale check run lingers).++## The Copilot reviewer is separate++GitHub Copilot reviews PRs using `.github/copilot-instructions.md` and the+path-scoped `.github/instructions/*`. It is **advisory** β it posts a summary+(leading π΄/π‘/π’) and inline comments, and reads the gate labels to focus its+review, but it never sets or clears the gate.