Skip to content

[pull] master from supabase:master - #1286

Merged
pull[bot] merged 3 commits into
code:masterfrom
supabase:master
Sep 26, 2026
Merged

pull[bot] merged 3 commits into
code:masterfrom
supabase:master

Conversation

@pull

@pull pull Bot commented Sep 26, 2026 •

Copy link
Copy Markdown

See Commits and Changes for more details.


Created by pull[bot] (v2.0.0-alpha.4)

Can you help keep this open source service alive? 💖 Please sponsor : )

czenko and others added 3 commits September 25, 2026 20:04
Part 1 of 3. Stack: #50742 → #50744 → #50743.

## Problem

We have several problems:
- Style guidance lives in lots of places and need consolidation
- Our CONTRIBUTING guide has turned into one massive style document that
needs to be broken up



## Solution

Add `apps/docs/style-guide/` as plain markdown. 

| File | Covers |
| --- | --- |
| `README.md` | What the guide covers, who it's for, how to contribute,
and the references it defers to |
| `WORD_LIST.md` | Terminology, spelling, capitalization, and the
`agent` / `LLM` / `AI` distinction. Moved from `apps/docs/` with history
intact |
| `01-voice-and-tone.md` | Audience, brevity, sentence construction |
| `02-elements.md` | Which component renders each piece, and linking
conventions |
| `03-page-structure.md` | Document types, information types, grouping,
chunking, timeless documentation |

### New content

This guide is mostly rearrangement and glue, but it includes some new
content:
- Links and cross-reference formatting
- WORD_LIST entries for LLM and AI agent
- Timeless documentation guidance
- Accessibility guidance
- Sharper guidance on brevity and chunking

## Manual testing

1. Open `apps/docs/style-guide/` on this branch and confirm `README.md`
renders below the file list.
2. Follow every link in `README.md` and read the document through.
3. You can test by locally pointing an agent at the style-guide and
seeing that it makes great choices when revising a document.


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

* **Documentation**
* Added a documentation style guide covering voice and tone, page
structure, and guidance for writing procedures, code, tables, diagrams,
media, and links.
* Added a word list with preferred spelling, capitalization, and usage,
including guidance on inclusive and concise language.
* Added recommendations for reviewing documentation drafts and runnable
examples.
* Replaced the existing word list page’s content with a link to its new
location in the style guide.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Nik Richers <nik@validmind.ai>
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>
#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 -->
@pull pull Bot locked and limited conversation to collaborators Sep 26, 2026
@pull pull Bot added the ⤵️ pull label Sep 26, 2026
@pull
pull Bot merged commit 36371de into code:master Sep 26, 2026
3 of 17 checks passed
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 26, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

⤵️ pull documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant