dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-06 01:45:10 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
codex/fix-tanstack-e2e
supabase/AGENTS.md
T
Miranda Limonczenko 36371de151 docs: trim CONTRIBUTING to repo mechanics and point at the style guide (#50743) 
Part 3 of 3. Stack: #50742 → #50744 → #50743. Review #50742 and #50744
first.

Closes DOCS-1177

## Problem

`CONTRIBUTING.md` mixed how to write a page with how the repo is laid
out. That's why it reached 568 lines, and why a contributor looking for
either half reads past the other.

#50742 gives the writing half its own home.

## Solution

Trim `CONTRIBUTING.md` to repo mechanics, 568 lines down to 163.

**Removed**, now in the style guide: general principles, information
types, document types, components and elements, styling and grammar,
word usage.

**Kept**: the skills table, repo organization, guide and reference
structure, content reuse, search. Content listings keeps its data file,
ID rules, and test command here; the when-to-use-one part is in the
style guide.

**Added**: a table linking each style guide file.

Wire the contributor-facing entry points at the guide:

- `apps/docs/AGENTS.md` — gains a style guide section listing each file
separately, so an agent can load one file without the others. This
auto-loads for anything under `apps/docs`, making it the
highest-leverage pointer in the repo.
- Root `AGENTS.md` — claimed the skills are "the source of truth for
conventions." For docs content style that's now the guide, with the
skills as the process that applies it.
- `.github/pull_request_template.md`, `.coderabbit.yaml`,
`apps/docs/README.md`, `apps/docs/DEVELOPERS.md` — updated paths.

Drop the `.prettierignore` exemption for `apps/docs/CONTRIBUTING.md`.
It's short enough to format now, and a repo that publishes a style guide
shouldn't exempt its own contributing doc.

## Notes for review

Discoverability in a markdown-only guide is entirely these pointers, so
they're the load-bearing part of this PR rather than cleanup.

Both surviving anchor links into `CONTRIBUTING.md` target
`#ai-agent-skills-for-docs-authoring`, which is kept. No dangling
anchors.

This PR sits last in the stack on purpose. It deletes the style sections
that seven skill instructions referenced, so it has to land after #50744
rewires them.

## Manual testing

1. Open `apps/docs/CONTRIBUTING.md` and confirm every remaining section
is repo mechanics, and the style guide table links resolve.
2. Confirm `apps/docs/AGENTS.md` names each style guide file, in size
order: `WORD_LIST`, `01-voice-and-tone`, `02-elements`,
`03-page-structure`.
3. Run `grep -rn "apps/docs/WORD_LIST" --include="*.md"
--include="*.yaml" . | grep -v node_modules` and confirm only the
intentional stub matches.
4. Run `npx prettier --config prettier.config.mjs --check
apps/docs/CONTRIBUTING.md`.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Updated contributor guidance to distinguish writing conventions from
repository mechanics, with the style guide as the reference for
documentation style.
* Added style guide links and clarified when to use the writing and
editing skills.
* Revised the docs contribution guide with a style guide file list and
steps for adding content listings.
* Updated the pull request checklist to direct contributors to the
documentation skills for style guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-09-25 20:22:47 -07:00

76 lines
6.7 KiB
Markdown
Raw Permalink Blame History

# Supabase Monorepo
pnpm 11 + Turborepo monorepo. Requires Node >= 22.13.
## Structure
| Directory | Purpose |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `apps/studio` | Supabase Studio/Dashboard — has its own `apps/studio/AGENTS.md` (see below) |
| `apps/docs` | Documentation site — Next.js app router, MDX (port 3001, served under `/docs`) — has its own `apps/docs/AGENTS.md` |
| `apps/www` | Marketing website — Next.js, app + pages (port 3000) |
| `apps/design-system` | Component demos — source of truth for Studio UI patterns (port 3003) |
| `apps/ui-library` | shadcn-style registry site for Supabase UI blocks (port 3004) |
| `apps/lite-studio` | Lightweight Studio — different stack: React Router 7 + Vite + Tailwind v4 |
| `apps/kb` | Knowledge base — Astro — has its own `apps/kb/AGENTS.md` |
| `apps/learn` | Courses site — Next.js + Contentlayer (port 3007), early stage |
| `packages/ui` | Shared UI components (shadcn/ui based) — `import { Button } from 'ui'` |
| `packages/ui-patterns` | Composite components — subpath imports, e.g. `ui-patterns/AssistantChat` |
| `packages/common` | Shared utils, telemetry constants, feature flags |
| `packages/api-types` | Generated platform Management API types |
| `packages/pg-meta` | SQL builders for Postgres introspection (`SafeSqlFragment`) |
| `packages/shared-data` | Static data: pricing, plans, regions, error codes |
| `e2e/studio`, `e2e/docs` | Playwright E2E tests |
| `supabase/` | Local Supabase project: edge functions, migrations, config.toml |
## Common Commands
```bash
pnpm dev:studio # run Studio dev server → http://localhost:8082
pnpm dev:docs # run docs dev server
pnpm dev:www # run www dev server
pnpm dev:kb # run knowledge base dev server
pnpm test:studio # Studio unit tests (vitest)
pnpm e2e # Studio E2E tests (playwright)
pnpm build --filter=studio # build Studio
pnpm lint --filter=studio # lint Studio
pnpm typecheck # typecheck all packages
pnpm format # Prettier write (check: pnpm test:prettier)
pnpm generate:types # local DB types → supabase/functions/common/database-types.ts
pnpm api:codegen # platform Management API types → packages/api-types
```
## CI
Every PR must pass typecheck + lint (one workflow), Prettier, and a typos check. Other checks are path-filtered: Studio unit tests/build and the lint ratchet (ESLint warning count must not increase) run on `apps/studio/**` changes; app-specific test suites run on their own paths.
Never hand-edit generated files: `packages/api-types/types/**`, `**/routeTree.gen.ts`, `**/__generated__/**`, `apps/docs/features/docs/generated/**`, `apps/www/.generated/**`, `supabase/functions/common/database-types.ts`, `apps/docs/content/_partials/access-control/scoped_pat_*.mdx` (run `make -C apps/docs/spec generate.partials.access-control`).
## Conventions
**UI** — import from `'ui'`; primitives are shadcn/ui-based and exported unsuffixed (`Input`, `Select`, `Form`, …). Use `Button` — the in-house component and the standard everywhere (a raw shadcn `Button_Shadcn_` also exists but is rarely the right choice). Check `packages/ui/index.tsx` before creating new primitives. Higher-level patterns live in `packages/ui-patterns`.
**Styling** — Tailwind only, semantic tokens (`bg-muted`, `text-foreground-light`), no hardcoded colors.
**Exports** — named exports only; default exports are allowed only where a framework requires them (`pages/**`, `app/**`, config files — the eslint preset has the exact carve-out list). Lint-enforced across all apps via `eslint-config-supabase` (severity `warn` everywhere; hard-enforced in Studio by the lint ratchet).
**Language** — Use U.S. English everywhere.
**Public surfaces** — this repo is public: PR descriptions, issues, and code comments are world-readable. Keep internal content out of them: absolute production metrics (event counts, user counts, revenue figures: state percentages, ratios, or relative change instead), internal decision detail (vendor, legal, pricing, or strategy discussions), and competitor names (protocol identifiers such as user-agent strings are fine). Put that context in the Linear issue and link it.
## Skills
The skills in `.agents/skills/` are the source of truth for conventions. Load the relevant ones before working, don't guess. One exception: for docs **content** style, `apps/docs/style-guide/` is the source of truth and the docs skills are the process that applies it.
- `copywriting` — any user-facing text, anywhere in the monorepo
- `pm-the-docs` / `write-the-docs` / `edit-the-docs` / `ask-the-docs` / `review-the-docs` — anything under `apps/docs` (see `apps/docs/CONTRIBUTING.md` for the authoring skill model, and `apps/docs/style-guide/` for the content style rules they apply)
- `telemetry-standards` — PostHog events, `packages/common/telemetry-constants.ts`
- `dev-toolbar-review` — `packages/dev-tools`, `packages/common/posthog-client.ts`, `packages/common/feature-flags.tsx`
- `safe-sql-execution` — any code that builds or executes SQL against user databases
- `react-hook-form` — writing or modifying any form code, anywhere in the monorepo
- `vitest` / `vercel-composition-patterns` — generic unit-testing and React composition references
## Studio
Before working on anything in `apps/studio`, read `apps/studio/AGENTS.md` if it isn't already in context — it maps Studio tasks to required skills and covers the TanStack Start migration rules.
Reference in new issue View Git Blame Copy Permalink