mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 01:15:03 +03:00
Miranda Limonczenko
36371de151
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 -->
153 lines
9.2 KiB
YAML
153 lines
9.2 KiB
YAML
# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
|
|
|
|
# Don't inherit organization-level settings (they're tuned for other repos);
|
|
# this config is self-contained and unset values use CodeRabbit defaults.
|
|
inheritance: false
|
|
|
|
# Enrich linked issues with related code and potential solutions during review.
|
|
issue_enrichment:
|
|
auto_enrich:
|
|
enabled: true
|
|
|
|
reviews:
|
|
# Skip machine-generated / vendored files (mirrors .prettierignore). Keeps
|
|
# reviews focused on hand-written code and preserves rate-limit budget on
|
|
# large codegen diffs.
|
|
path_filters:
|
|
- '!pnpm-lock.yaml'
|
|
- '!packages/api-types/types/**' # generated API types (api.d.ts, platform.d.ts)
|
|
- '!supabase/functions/common/database-types.ts' # generated by `pnpm generate:types`
|
|
- '!**/routeTree.gen.ts' # TanStack Router generated
|
|
- '!**/__generated__/**'
|
|
- '!apps/docs/features/docs/generated/**'
|
|
- '!apps/www/.generated/**'
|
|
- '!apps/design-system/__registry__/**'
|
|
- '!apps/ui-library/__registry__/**'
|
|
- '!apps/ui-library/public/r/**' # registry output
|
|
- '!packages/icons/__registry__/**'
|
|
- '!packages/icons/src/icons/**' # generated icon components
|
|
|
|
# Targeted, path-scoped review guidance, version-controlled alongside the code.
|
|
path_instructions:
|
|
- path: 'packages/common/telemetry-constants.ts'
|
|
instructions: |
|
|
Strictly enforce event naming: [object]_[verb] in snake_case. Only approved
|
|
verbs: opened, clicked, submitted, created, removed, updated, retrieved,
|
|
intended, evaluated, added, enabled, disabled, copied, exposed, failed,
|
|
converted. Properties must be camelCase for new events (match existing
|
|
convention when adding to existing events). Flag any usage of
|
|
useSendEventMutation. Verify @group Events and @source JSDoc tags are
|
|
accurate. Check that new interfaces are added to the TelemetryEvent union type.
|
|
- path: 'apps/studio/components/**/!(*.test).tsx' # production components only, not tests
|
|
instructions: |
|
|
Only suggest adding PostHog event tracking (via useTrack from
|
|
lib/telemetry/track, [object]_[verb] snake_case) when a new user-facing
|
|
interaction is growth-relevant: e.g. first-use of a feature, onboarding steps,
|
|
project/org creation, upgrade/billing actions, enabling or disabling a product
|
|
feature, or any action that signals activation or retention. Do not suggest
|
|
tracking for: passive views, page loads, UI-only state changes (e.g. expanding
|
|
a panel, switching tabs in a settings page), developer/internal tooling
|
|
interactions, or interactions clearly unrelated to product adoption.
|
|
- path: 'apps/studio/pages/**'
|
|
instructions: |
|
|
Studio is mid-migration from the Next.js pages router (apps/studio/pages/**)
|
|
to TanStack Start (apps/studio/routes/**). Both runtimes ship side-by-side, so
|
|
every URL served from pages/** has a mirror in routes/**. See
|
|
apps/studio/TANSTACK_MIGRATION.md for the full route map and strategy.
|
|
Leave a comment reminding the author to check whether this change needs to be
|
|
mirrored into the corresponding apps/studio/routes/** file so the two builds
|
|
don't silently drift:
|
|
- Most route files re-export the page's default export (Path A), so pure
|
|
page-body edits propagate automatically — no mirror needed.
|
|
- A mirror IS needed when the change touches something the route file
|
|
duplicates rather than imports: getLayout / layout wrapping, page title or
|
|
other props the route encodes as staticData, withAuth / auth gating, or the
|
|
route/redirect path itself.
|
|
- A brand-new page under pages/** needs a matching new route under routes/**
|
|
(and a checklist entry in apps/studio/TANSTACK_MIGRATION.md).
|
|
- Do NOT suggest deleting the pages/** file — the Next file stays load-bearing
|
|
for both runtimes until the final cleanup pass (tracked in FE-3106).
|
|
Keep this a reminder to verify, not a hard blocker: if no mirror is required,
|
|
say so briefly rather than forcing a change.
|
|
- path: 'apps/docs/content/**/*.mdx'
|
|
instructions: |
|
|
Flag style, terminology, and structure issues as usual. When a page has two or
|
|
more of them, add one comment pointing the author at the `/write-the-docs` skill
|
|
for new content or `/edit-the-docs` for an existing page (canonical files in
|
|
`.agents/skills/`); both apply the docs style guide in
|
|
apps/docs/style-guide/. Skip that pointer on a single issue, so it stays a
|
|
signal that the author isn't using the skills rather than boilerplate.
|
|
- path: '{apps,packages}/**/*.{tsx,jsx,css,mdx}'
|
|
instructions: |
|
|
When reviewing UI changes, flag these accessibility gaps. Comments are
|
|
advisory. One comment per gap. Skip test files (*.test.*, *.spec.*) and
|
|
generated files. Skip Radix/shadcn primitives imported from ui for all
|
|
checks below. Do not flag issues axe-core already catches mechanically,
|
|
such as a missing alt attribute, an empty button or link name, or
|
|
invalid ARIA.
|
|
- State changes: if sighted users can see a status change (toast,
|
|
loading/empty swap, copy confirmation, async result) and nothing
|
|
announces it, suggest aria-live="polite" or role="status". Reserve
|
|
role="alert" for urgent errors or warnings. Skip if a live region,
|
|
Radix Toast, or Sonner is already there, or if the change is
|
|
decoration only. If a live region is created in the same conditional
|
|
as its message, flag that: the region must already exist in the DOM,
|
|
then receive the update, or screen readers often announce nothing.
|
|
- Mouse interaction: flag pointer-only handlers on a non-interactive
|
|
element (div, span, or similar) with no keyboard equivalent. The
|
|
listed handlers are illustrative: onClick, onMouseEnter,
|
|
onDoubleClick, onContextMenu, onPointerDown, onPointerUp,
|
|
onTouchStart, onTouchEnd, and equivalents. Also flag hover-only UI
|
|
(content revealed with onMouseEnter or CSS :hover) that has no focus
|
|
or keyboard path.
|
|
- Animation: flag animate-*, keyframes, or JS motion with no
|
|
reduced-motion treatment. Prefer Tailwind motion-reduce: /
|
|
motion-safe:, or matchMedia('(prefers-reduced-motion: reduce)').
|
|
packages/config/css/utilities.css only zeroes out .shimmer under
|
|
reduced motion, not all animation.
|
|
- Alt text: flag generic values such as Image, Icon, Photo, Picture, or
|
|
the filename. Flag alt that starts with "image of" or "picture of".
|
|
If adjacent visible text already names the image (blog thumbnail next
|
|
to its title, icon next to its label), flag it as redundant and
|
|
recommend alt="" plus aria-hidden on the image. For a decorative SVG
|
|
next to visible text, recommend aria-hidden on the SVG. If alt is
|
|
longer than about two sentences, suggest moving the extra into a
|
|
caption, adjacent text, or aria-describedby. Do not treat a character
|
|
count as a hard fail.
|
|
- Focus visibility: flag outline-none, outline-hidden, outline: none,
|
|
outline: 0, or equivalent :focus resets that are not paired with a
|
|
focus-visible ring or outline, or with the focus-ring or focus-inset
|
|
utility.
|
|
- Color-only state: flag status, validation, or selection that is
|
|
conveyed only by color. Suggest a text label, icon, or sr-only text
|
|
in addition.
|
|
- Link purpose: flag an accessible name that is only "click here",
|
|
"read more", or "learn more" when it does not describe the
|
|
destination. Skip if aria-label or wrapping context already names
|
|
where the link goes.
|
|
- Color contrast: flag non-large informative text below 4.5:1 and large informative
|
|
text (at least 24px regular or 18.5px bold) below 3:1. Skip logotypes and
|
|
decorative text. Treat expressive text at 40px or larger as advisory rather
|
|
than blocking.
|
|
|
|
# Applies our internal engineering skills (.agents/skills/) as CodeRabbit review
|
|
# guidelines. The skills are the single source of truth — they are consumed
|
|
# directly, with no copy of their content elsewhere.
|
|
#
|
|
# `applyTo` decouples where a guideline file lives from the code it governs.
|
|
# Without it, CodeRabbit scopes a guideline file to its own directory and below;
|
|
# our skills live in .agents/skills/, which contains no code, so they would never
|
|
# reach apps/studio. `applyTo` points them at the right paths instead.
|
|
knowledge_base:
|
|
code_guidelines:
|
|
filePatterns:
|
|
# Studio code conventions — React/TS, UI patterns, composition, data fetching, errors
|
|
- files: '.agents/skills/{studio-ui-patterns,vercel-composition-patterns,studio-queries,studio-error-handling,react-hook-form}/SKILL.md'
|
|
applyTo: 'apps/studio/**/*.{ts,tsx}'
|
|
# Studio unit / component test conventions
|
|
- files: '.agents/skills/{studio-testing,studio-mock-api-tests}/SKILL.md'
|
|
applyTo: 'apps/studio/**/*.test.{ts,tsx}'
|
|
# Studio end-to-end (Playwright) test conventions
|
|
- files: '.agents/skills/studio-e2e-tests/SKILL.md'
|
|
applyTo: 'e2e/studio/**/*.spec.ts'
|