mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03:00
bot/decrease-eslint-ratchet-baselines
6
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Miranda LimonczenkoandNik Richers
|
f5fcecf3d7 |
docs: point the authoring skills at the style guide (#50744)
Part 2 of 3. Stack: #50742 → #50744 → #50743. Review #50742 first. ## Problem Six skills restated style rules inline, so a rule could be corrected in the guide and stay wrong in a skill. `edit-the-docs` alone carried a second copy of the procedure format, the information-type classification rules, and the tables outline example. Two reference files said in their own text that they should be retired once a style guide existed. ## Solution Replace the restatements with pointers to the file that owns each rule. **Retired, as each file asked:** - `style-fallback.md` is deleted. It ended by telling an agent to follow the nearest comparable page, which launders whatever that page happens to do into a rule. The guide's References section replaces it. - `common-pitfalls.md` becomes a pointer, per the note at its own line 94. **Rewired**: `write-the-docs`, `edit-the-docs`, `review-the-docs`, `pm-the-docs`'s checklist, and `drafting-mechanics.md`. Skills cite a specific file rather than the directory, so one file can be loaded instead of the whole guide. `review-the-docs` gains a docs-tooling check for the inverse case: a style rule added to a skill belongs in the guide, with the skill pointing at it. ## Notes for review **`edit-the-docs`' PR 1 / PR 2 boundary is unchanged on purpose.** That split is by kind of diff — PR 1 is inline changes only, nothing moves a line — which is what makes each PR reviewable. The guide's files split by the size of the thing they govern, and the two cut across each other: choosing an admonition is an element decision but an inline diff, and chunking is a page-structure decision but currently applied in PR 1. Forcing them to match would stop PR 1 being a pure inline pass. Dropping the dash-aside rule from `write-the-docs` here lost it entirely, since it had no home in the guide. #50742 restores it in `01-voice-and-tone.md`. I audited the other four rules this PR removes from that checklist; only that one was lost. The skill's document-type list keeps `troubleshooting`, which CodeRabbit flagged as a fifth type not in the guide. The repo has 219 troubleshooting pages and a content-type gate that treats them as authorable, so the gap was in the guide. #50742 now lists five document types. ## Manual testing 1. Run `grep -rn "style-fallback\|apps/docs/WORD_LIST" .agents/skills/` and confirm no matches. 2. Open each rewired skill and confirm every style guide link resolves, including anchors such as `03-page-structure.md#chunking`. 3. Invoke `/edit-the-docs` and confirm it reads the guide rather than restating rules. 4. Run `npx prettier --config prettier.config.mjs --check ".agents/skills/*-the-docs/**/*.md"`. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated documentation writing, editing, and review guidance to reference the dedicated style guide for voice, terminology, page structure, and content elements. * Clarified how to classify and organize sections, and expanded style-consistency checks. * Updated related checklists and references to distinguish style guidance from repository contribution instructions. * Consolidated common drafting advice into the style guide and updated the page-type table layout. <!-- end of auto-generated comment: release notes by coderabbit.ai --> ## Stack order This PR moved above the `CONTRIBUTING.md` trim after review. The trim deletes the style sections that seven skill instructions still referenced, so trimming first left those references dangling until this PR landed. Rewiring the skills first removes that intermediate state: the skills point at the guide while `CONTRIBUTING.md` is still whole, and the trim then breaks nothing. --------- Co-authored-by: Nik Richers <nik@validmind.ai> |
||
|
Miranda Limonczenko
|
7ce4ee53ae |
chore(docs) Retire supa-mdx-lint (#50602)
Closes [DOCS-1289](https://linear.app/supabase/issue/DOCS-1289/get-the-linter-to-fix-what-it-flags-or-retirereplace-the-linter) Stacked on #50600, which points contributors at the authoring skills. Merge that one first. ## Problem Contributors experienced friction with the linter. They felt nickle and dimed for tiny nits and felt detracted from the work itself. PRs would become noisy with tiny one-word suggestions. Additionally, our homegrown linter is not very intelligent, causing frequent overrides. ## Solution This removes the linter entirely in favor of directing contributors to use SKILLS instead. The removal entails... - **CI.** Delete the three `docs_lint` workflows: the PR check, the external-PR comment companion, and the nightly `--fix` bot. Drop the stale `zizmor.yml` ignore entry for the deleted workflow. - **Tooling.** Delete `supa-mdx-lint.config.toml` and the 14 rule files. Drop the `lint:mdx` script and the `@supabase/supa-mdx-lint` dependency from docs, learn, and ui-library, and regenerate the lockfile. - **Content.** Remove the 181 directives. A separate commit carries Prettier's reformatting of the tables and blank lines those comments had suppressed, so the deletion commit stays readable. No prose changes. - **Style guide.** The word list states each rule directly instead of describing what the linter flagged. Every term survives, including the phrase groups that mirrored `Rule004ExcludeWords`. - **Skills.** `write-the-docs`, `edit-the-docs`, and `review-the-docs` drop `pnpm lint:mdx` from their self-review commands and check the word list directly. `ask-the-docs`'s CI reference drops both workflows. ## Manual testing 1. Run `git grep -i supa-mdx-lint -- . ':!pnpm-lock.yaml'`. No matches. 2. Run `pnpm install --frozen-lockfile --lockfile-only`. It passes, so the lockfile matches the three trimmed manifests. 3. Run `git diff master...HEAD --name-only --diff-filter=ACMR | grep -E '\.(md|mdx)$' | xargs npx prettier --config prettier.config.mjs --check`. All changed markdown passes. 4. Open the [reformatted filter table](https://docs-git-docs-retire-mdx-linter-supabase.vercel.app/docs/guides/observability/logs#filter-events) on the preview and compare it with [production](https://supabase.com/docs/guides/observability/logs#filter-events). The table renders the same. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Documentation guidance now uses manual prose and terminology review with the shared word list. * Clarified storage configuration and common Realtime channel mistakes. * Improved table formatting, text wrapping, and selected reference links. * Updated documentation authoring and review guidance. * **Chores** * Retired automated MDX linting from workflows and local validation commands. * Removed lint-suppression markers throughout documentation without changing instructions. * Added targeted documentation review guidance for pull requests. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
Nik RichersandNik Richers
|
0322720743 |
docs: add test-the-docs skill and pm-the-docs universe lookup (#49913)
## I have read the CONTRIBUTING.md file. YES ## What kind of change does this PR introduce? Docs authoring skills / contributor enablement. ## What is the current behavior? - The "Write the docs" bar asks for runnable examples, but skills stop at lint/build (`/review-the-docs`) and do not execute inline MDX snippets. - Cross-repo product grounding depends on a single-repo read; there is no skill guidance for `supabase/universe` when you have Supabase org access. ## What is the new behavior? - Adds `/test-the-docs` to run procedural snippets against a Docker-isolated local stack (`supabase start` in a temp project), with Verification table output. - Teaches `/pm-the-docs` cross-repo product lookup (`reference/universe-lookup.md`) with a capability gate: universe when you have Supabase org access (or a local clone), otherwise a first-class OSS public-search path. `ask-the-docs` stays docs-app only. - Updates the checklist mirror, CONTRIBUTING skills table, and light handoffs in `write-the-docs` / `review-the-docs`. ## Additional context Vault "Write the docs" checklist updated separately; Linear document needs a Claude-side delta sync after merge. ### Test plan - [ ] Symlinks: `.claude/skills` is a Git symlink to `../.agents/skills`; `.claude/skills/test-the-docs/SKILL.md` resolves - [ ] No hardcoded personal absolute paths under `.agents/skills/` - [ ] CONTRIBUTING lists skills including `/test-the-docs` - [ ] `/pm-the-docs` references `universe-lookup.md` capability gate; `/ask-the-docs` Related points there for product lookup - [ ] OSS path: no universe clone / submodule init when `gh api repos/supabase/universe` fails - [ ] Docker up: dry-run `/test-the-docs` against one MDX page with SQL/CLI (optional smoke) - [ ] Docker down: skill documents graceful `deferred` (not silent skip) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Added documentation guidance for testing runnable examples in an isolated local environment. - Added cross-repository product lookup guidance, including capability checks and source tracking. - Added verification report templates with standardized results and environment details. - **Documentation** - Expanded authoring, review, self-review, and contribution guidance. - Improved safety instructions for local snippet testing, including credential protection and cleanup. - Updated repository layout, tooling, links, and workflow references for documentation skills. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Nik Richers <nik@validmind.ai> |
||
|
Alaister YoungandAlaister Young
|
f125126aec |
chore: make agent instructions agent-agnostic (#49941)
Makes the repo's AI-agent setup tool-agnostic: instructions live in
`AGENTS.md` files, skills live in `.agents/skills/`, and Claude Code,
Codex, Cursor, and Copilot all read the same sources. Also sweeps the
skills for stale and duplicated content while everything was being
moved.
**Changed:**
- Every `CLAUDE.md` (root, `apps/studio`, `apps/docs`, `apps/kb`) is now
a one-line `@AGENTS.md` import; the content moved verbatim into an
`AGENTS.md` beside it. The root one moved from `.claude/CLAUDE.md` to
the repo root for consistency.
- All skills now live in `.agents/skills/`; `.claude/skills` is a single
symlink to it (replacing the old mix of real dirs and per-skill
symlinks). Path references in `.coderabbit.yaml`, code comments, and
docs updated to match.
- `.github/copilot-instructions.md` keeps only the review policy and
points at `AGENTS.md` + `.agents/skills/`. Copilot code review reads
those natively now, so the per-topic
`.github/instructions/*.instructions.md` files were duplicates of the
skills.
- Stale skill content fixed: `studio-queries` imported a toast library
Studio doesn't use, `telemetry-standards` and `studio-testing` used
import paths that don't resolve, `safe-sql-execution` cited a boundary
test that doesn't exist, the ask-the-docs references described an
`AiPrompt` mechanism that was replaced by the ID-keyed registry, plus a
handful of wrong paths, a self-contradicting `waitForTimeout` rule, an
invalid Playwright signature, and a ConfigCat flag described as PostHog.
- `studio-error-handling` now explains when to use `AlertError` (the
default) vs `ErrorMatcher`.
**Added:**
- `apps/docs/AGENTS.md` (docs test requirements, from the old Cursor
rule)
- `studio-shortcuts` skill (from the old Copilot instruction file,
verified against the current registry)
- `ask-the-docs/reference/graphql-endpoint.md` and
`search-embeddings.md` (from the old Cursor rules, with the missing
resolver/registration/codegen steps filled in)
- Feature-flag measurement section in `telemetry-standards`
**Removed:**
- `.cursor/` (rules folded in as above; skill symlinks no longer needed)
and `.cursorignore`
- `.github/instructions/` (8 files)
- `vercel-composition-patterns/AGENTS.md` – a 946-line verbatim
concatenation of its own `rules/` directory, and a nested `AGENTS.md`
that agents could auto-load as repo instructions
- `edit-the-docs/reference/structure-and-flow.md` – word-for-word copy
of the skill's own Phase 2 text
## To test
- `readlink .claude/skills` → `../.agents/skills`, and `ls
.claude/skills/copywriting/SKILL.md` resolves
- Open a Claude Code session at the repo root and in `apps/studio` – the
imported `AGENTS.md` content should load as before
- `git diff master --stat -M` shows the skill moves as 100% renames
(content unchanged except the listed fixes)
- Spot-check a fixed claim, e.g. `import { toast } from 'sonner'` in
`studio-queries`, or the `logs.all` ESLint rule cited in
`clickhouse-logs-queries/references/codebase-integration.md`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Expanded guidance for documentation workflows, GraphQL resources,
search, ClickHouse logs, React forms, Studio testing, shortcuts,
telemetry, accessibility, copywriting, and composition patterns.
- Clarified local testing, linting, build workflows, error handling, and
AI coding agent usage.
- Added contributor guidance for the knowledge base, documentation, and
Studio areas.
- **Chores**
- Consolidated agent instructions and skill references.
- Removed obsolete editor-specific guidance, duplicate links, and
superseded documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
|
||
|
|
a27f81d5a0 |
docs: improve write-the-docs skill and retire docs-content (#49089)
## I have read the CONTRIBUTING.md file. YES ## What kind of change does this PR introduce? Improves the `write-the-docs` skill and retires the overlapping `docs-content` skill (provided @czenko agrees to the latter). ## What is the current behavior? - Docs drafts could leak future-tense / internal roadmap language, add redundant verbiage, and add single-item lists. - No explicit CONTRIBUTING.md / WORD_LIST.md compliance pass for docs drafts. - Product intent was assumed to come from Linear without a good path path for open-source contributors. - `docs-content` overlapped `write-the-docs` and the broader `*-the-docs` skill set (e.g. I started [#49432](https://github.com/supabase/supabase/pull/49432) before realizing we should likely not have overlapping skills). ## What is the new behavior? - Codifies draft pitfalls as principles in `reference/common-pitfalls.md` (timelessness, strip internal business context, redundancy, single-item lists), with style detail pointed from `SKILL.md` rather than duplicated. - Clarifies SoT: Linear + code inspection for content accuracy; CONTRIBUTING.md / WORD_LIST.md (and future DOCS-1177 style guide) for voice/terminology/formatting only. `common-pitfalls.md` is flagged to fold into that guide later. - Linear is internal and preferred when available, not required for open-source. Missing product intent: stop Draft and hand off to `pm-the-docs` (Frame) / `ask-the-docs` (Shape/IA); do not invent positioning or run Frame/Shape inside this skill. - Adds drafting mechanics notes, a compliance checklist before handoff, and a local `/review-the-docs` self-review step. - Removes `.claude/skills/docs-content/`; `.claude/CLAUDE.md` points at the canonical docs skills. Supersedes #49432. ## Additional context Based on @czenko review feedback on #49020 and feedback I received for `docs-content` from @aantti while trialing the "Write the docs" process with contributors, plus my own testing while drafting docs for product managers. ### Test plan - [ ] `SKILL.md` reads as Draft-only; Frame/Shape stay with `pm-the-docs` / `ask-the-docs` - [ ] No-Linear path: ask for Linear (internal) or hand off Frame/Shape; no invented positioning - [ ] `.claude/skills/docs-content/` gone; `.claude/CLAUDE.md` updated - [ ] `.claude/skills/write-the-docs` symlink still resolves to `.agents/skills/write-the-docs` - [ ] Next `/write-the-docs` run: compliance re-read + pitfalls guidance before handoff <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added an `edit-the-docs` workflow for restructuring and improving existing documentation pages. - Expanded authoring guidance for concise, timeless, user-focused content grounded in product intent. - Added references covering common writing pitfalls, link and anchor conventions, and validation workflows. - Clarified that style guidance applies to voice, formatting, and terminology—not product behavior. - Updated documentation workflows to distinguish planning, writing, editing, review, and assistance responsibilities. - Replaced the previous standalone docs-content skill with the updated authoring skill model. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Nik Richers <nik@validmind.ai> Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io> |
||
|
Nik RichersandNik Richers
|
cf36ad9e52 |
feat(skills): move Write the docs skills into the monorepo — DO NOT REVIEW YET (#48914)
## I have read the CONTRIBUTING.md file. YES ## What kind of change does this PR introduce? Adds four AI agent skills that support docs contributors across the authoring lifecycle, intended to lower the barrier to entry for contributing to our docs. Closes DOCS-1287. ## What is the current behavior? Our process for writing docs is somewhat undefined beyond some general guidance in CONTRIBUTING.md and we don't make as easy to contribute to our docs as we could. As a result, content often needs additional changes during PR reviews or requires further revisions after merging. The four AI agent skills in this PR already existed in a private repo where I've been testing them but they were not previously available for general use until now. ## What is the new behavior? - Four skills added under `.agents/skills/`, symlinked from `.claude/skills/` and `.cursor/skills/` (same pattern as the existing `vitest` skill). - `ask-the-docs`: answers architecture and design questions about apps/docs (MDX pipeline, content components, federated docs) and checks whether a proposed change fits existing docs app patterns. - `write-the-docs`: drafts net-new or substantially rewritten docs content for a feature or launch, grounded in the Linear ticket, the actual code, and the docs style guide. - `review-the-docs`: runs a local, PR-type-specific review checklist against any open supabase/supabase docs PR (markdown pipeline, MDX content, tutorials, examples, Studio links) and produces a consolidated report. - `pm-the-docs`: supports "Write the docs" authoring process across the different phases. - `apps/docs/CONTRIBUTING.md` gets a new "AI agent skills for docs authoring" section mapping each skill to its checklist stage - Cross-references to skills that stay in `docs-agent-skills` (`work-linear-issue`, `audit-docs-ia`, `create-pull-request`, `proof-it-works`, `pm-the-docs-full`) now point there via absolute GitHub links instead of relative paths ## Additional context - Companion PR: [supabase/docs-agent-skills#28](https://github.com/supabase/docs-agent-skills/pull/28). Removes the three moved skills, renames `pm-the-docs` to `pm-the-docs-full`, and fixes now-dangling inbound links. - Worktree: `~/GitHub/supabase/supabase-worktrees/nikrichers/docs-1287-move-skills-mentioned-in-write-the-docs-from-docs-agent` - Opened as draft: this is a docs-authoring-tooling change with no runtime/build surface. Flip to ready once you've sanity-checked the skill content. ### Test plan - [ ] `ls -la .claude/skills/{ask-the-docs,pm-the-docs,write-the-docs,review-the-docs}` resolves to `.agents/skills/...` - [ ] Open a fresh Claude Code session with cwd in this repo and confirm `/ask-the-docs`, `/pm-the-docs`, `/write-the-docs`, `/review-the-docs` are available - [ ] Read the new section in [`apps/docs/CONTRIBUTING.md`](apps/docs/CONTRIBUTING.md) in context - [ ] Spot-check `.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md` has no `linear.app` links and carries the snapshot disclaimer --------- Co-authored-by: Nik Richers <nik@validmind.ai> |