Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
76 lines (61 loc) · 3.09 KB

CONTRIBUTING.md

File metadata and controls

76 lines (61 loc) · 3.09 KB
Raw

Contributing to SlotScope

Toolchain (exact, enforced)

  • Node 24.18.0 (.node-version, engines.node; engine-strict is on)
  • pnpm 11.17.0 via corepack: corepack prepare pnpm@11.17.0 --activate
  • Foundry/Forge 1.5.1-stable (independent storage-layout cross-check)

Every direct dependency is pinned exactly; save-exact is set. Adding a range, tag, or floating reference fails pnpm deps:policy and CI.

Bootstrap

pnpm install --frozen-lockfile
pnpm --filter @slotscope/web exec playwright install chromium

Commands

pnpm format:check   # prettier
pnpm lint           # eslint
pnpm typecheck      # tsc -b project references
pnpm test:unit      # vitest unit + property suites (all packages + scripts)
pnpm test:fixtures  # fixture ground-truth suite incl. Forge cross-check
pnpm test:e2e       # Playwright browser suites (builds + previews first)
pnpm test:a11y      # accessibility subset only
pnpm fixtures:verify        # golden drift check (CI mode)
pnpm build && pnpm build:check  # production build + payload inventory gate
pnpm benchmark:v0.1 # reference benchmark (after pnpm build)
pnpm release:verify # release evidence check

Rules that block merges

  • Fixture goldens change only through node scripts/verify-fixtures.ts --update in a reviewed commit; the command prints a semantic diff — review the facts, not just hashes.
  • Correctness and benchmark jobs run with zero retries and are never continue-on-error.
  • Every animated state needs a persistent border/icon/text equivalent, and every interactive surface must pass the keyboard + reduced-motion suites (see packages/ui/src/tokens.css for the motion contract).
  • No new dependencies, packages, or abstractions beyond what the public fixture slice demands (plan risk R11).

Architecture

See docs/architecture.md and the ADRs in docs/adr/.

Workflow

  1. Issues live in beads (bd ready, bd show <id>, bd update <id> --claim, bd close <id>); create an issue before writing code.
  2. One task, one commit: each closed issue maps to a focused commit whose message says what changed and why.
  3. Every commit must leave every gate green — there are no allowed-failure jobs and no retries for correctness or benchmark assertions.
  4. master is branch-protected: work happens on a branch, opens a PR, and merges only once every required check (quality, unit-fixtures, build, browser, release-verify) is green. No force-pushes, no direct deletion, linear history only.
  5. Deployment is native: Vercel is connected to master and redeploys production automatically on every merge (Build Command pnpm build, Output Directory apps/web/dist). A manual vercel deploy --prebuilt --prod is only for verifying a build locally before it lands.

Design system

All colors, spacing, type, and motion come from packages/ui/src/tokens.css; raw hex outside that file is a review defect. The one aesthetic rule: amber is forbidden on any control — only measured values glow. See docs/design/instrument-identity-v0.15.md.