Skip to content

Commit 3bd8a10

Browse files
ukimsanovukimsanov
committed
docs: add documentation quality gates
1 parent 6b76f08 commit 3bd8a10

35 files changed

Lines changed: 1011 additions & 890 deletions

‎docs/AGENTS.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# HyperFrames documentation rules
2+
3+
Before changing a page, read its complete body and verify product behavior in
4+
the current source, tests, CLI help, or shipped skills.
5+
6+
- Write for a smart general user first. Do not assume they are a developer.
7+
- Explain what a person can accomplish before explaining implementation details.
8+
- Prefer plain words, short examples, screenshots, and visible outcomes.
9+
- Keep agent instructions copyable and specific.
10+
- Put CLI, SDK, package, schema, deployment, and internals under **Developers**.
11+
- Never infer product behavior from page titles or old docs. Verify it in current code.
12+
- Do not preserve a page merely because it already exists. Merge, rewrite, redirect, or remove it when that improves the user journey.
13+
- Do not publish empty, duplicated, outdated, or aspirational content as fact.
14+
- A page should answer a real question or help complete a real task.
15+
- Preserve the approved Mintlify header, sidebar, right-side contents, and page-width behavior unless a task explicitly changes the site chrome.
16+
17+
## Page standard
18+
19+
Most human-facing pages should contain:
20+
21+
1. What this lets you do
22+
2. When to use it
23+
3. A visual or concrete example
24+
4. The shortest successful path
25+
5. What should happen
26+
6. Common problems
27+
7. Useful next steps
28+
29+
Do not force this structure where it makes a page worse. Reference pages may stay reference-shaped.
30+
31+
## Component doctrine
32+
33+
One component per job. If two components on a page render the same list, delete one.
34+
35+
| The job | Use | Never use |
36+
| --- | --- | --- |
37+
| Choose between destinations | `CardGroup` + `Card`, max 2 columns, linking to the real page | An accordion, or cards pointing at anchors on the same page |
38+
| Ordered instructions | `Steps` | A flow diagram that repeats the same steps |
39+
| Parallel variants of one instruction (source type, OS, language) | `Tabs` | Repeating the whole block per variant |
40+
| Compare attributes across items | A table | Prose paragraphs per item |
41+
| Static image | `Frame` with a caption that says what it is | A bare `img` with no context |
42+
| Genuinely out-of-band aside | One `Note`, `Tip`, or `Warning` per page | Stacked callouts, or a callout for ordinary prose |
43+
44+
**Do not use accordions for journeys, choices, instructions, or troubleshooting.** They hide the thing the reader needs, cost a click, and weaken `Cmd+F`, printing, and deep linking. A dense optional reference or example gallery may keep accordions when showing every item at once would make the page unusable; the Prompt Guide's verified-example gallery is the existing exception. Long symptom or task lists become visible `##` sections instead — they get anchors the support team can link directly, and they appear in the page contents.
45+
46+
**No diagram that restates adjacent prose.** A four-node flow beside a four-step list is the same content twice. Keep whichever is more useful and delete the other.
47+
48+
**Cards link to pages, never to anchors on the current page.** A card that scrolls the reader a short distance to the same words is the worst pattern in these docs; it has been removed twice.
49+
50+
**Two columns is the practical maximum** for anything containing text. Three columns in this content width hyphenates titles mid-word.
51+
52+
**Full films and preview loops are different jobs.** Use `DocsVideo` for a
53+
narrated film a reader watches intentionally. A plain `<video>` is only for a
54+
small, muted, autoplaying preview loop inside a visual explanation or Catalog
55+
item. Do not mix native browser controls with the custom player.
56+
57+
**Related topics must be visible content.** Mintlify does not render a
58+
`related:` frontmatter list. Add a final `## Related topics` section with only
59+
the two or three destinations that genuinely help the reader continue.
60+
61+
### Custom React components
62+
63+
Mintlify compiles `.jsx` / `.tsx` from `docs/snippets/`. Use one when a native component genuinely cannot express the idea — a scrubber, a comparison slider, a live player — not for styling.
64+
65+
- Named exports only: `export const Thing = () => ...`. Default exports do not work.
66+
- `useState`, `useEffect`, `useRef`, `useCallback`, `useMemo`, `useContext`, `useReducer` are pre-injected; do not import React.
67+
- **Do not add a dependency or CDN script for presentation alone.** Prefer browser built-ins (`fetch`, `IntersectionObserver`, Canvas, `<video>`). A version-pinned official runtime is acceptable when that runtime is the subject of the demo and the component provides a useful loading or failure state; the live composition on Introduction is the model.
68+
- A snippet cannot import another snippet. Keep each self-contained.
69+
- **Declare everything inside the component.** Only the exported component survives
70+
compilation; module-level `const`s above it are dropped, so a constant defined
71+
outside arrives `undefined` at render. The component then throws inside React,
72+
the error boundary swallows it, and the page renders nothing at that position —
73+
with no console error to point at it. If a snippet renders blank, check this first.
74+
- Client-side only: guard anything touching `window` and give every component a sensible first paint.
75+
- Respect `prefers-reduced-motion`, give interactive elements a visible focus state, and never make a component the only route to information.
76+
77+
## Verification
78+
79+
After navigation or MDX changes:
80+
81+
```bash
82+
PATH=/opt/homebrew/opt/node@20/bin:$PATH mint validate
83+
PATH=/opt/homebrew/opt/node@20/bin:$PATH mint broken-links
84+
```
85+
86+
Use Bun for repository work. Do not create a `pnpm-lock.yaml`.
87+
88+
## Freshness and ownership
89+
90+
- A product behavior page is owned by the team that owns the matching product surface.
91+
- A package or API reference is owned by the package maintainer.
92+
- Workflow pages are owned by the maintainer of the matching agent skill.
93+
- When a feature changes, update its task guide, related troubleshooting entry, and screenshot in the same pull request.
94+
- Treat screenshots as product claims. Replace them when labels, layout, or the demonstrated workflow changes materially.
95+
- Review **Start here**, **Studio**, **Export**, and **Troubleshooting** at least once per release cycle.
96+
- Review lower-traffic reference pages at least quarterly.
97+
- Remove an unowned update feed instead of letting it become stale.
98+
- Use search analytics and support questions to decide which missing task pages to add next.

‎docs/contributing.mdx‎

Lines changed: 51 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -1,168 +1,79 @@
11
---
2-
title: Contributing
3-
description: "How to contribute to Hyperframes."
2+
title: Contribute to HyperFrames
3+
description: Set up the repository, make a focused change, and open a pull request.
44
---
55

6-
Thanks for your interest in contributing to Hyperframes! This guide covers everything you need to get set up, run tests, and submit a pull request.
7-
8-
## Getting Started
9-
10-
<Steps>
11-
<Step title="Fork and clone">
12-
Fork the repository on GitHub, then clone your fork:
13-
```bash
14-
git clone https://github.com/YOUR_USERNAME/hyperframes.git
15-
cd hyperframes
16-
```
17-
</Step>
18-
<Step title="Install dependencies">
19-
Hyperframes uses [bun](https://bun.sh/) for package management:
20-
```bash
21-
bun install
22-
```
23-
</Step>
24-
<Step title="Build all packages">
25-
Build the monorepo to ensure everything compiles:
26-
```bash
27-
bun run build
28-
```
29-
</Step>
30-
<Step title="Run the studio">
31-
Start the development server to verify your setup:
32-
```bash
33-
bun run dev
34-
```
35-
If the studio opens at `http://localhost:5190` with a preview, your environment is ready.
36-
</Step>
37-
<Step title="Create a branch">
38-
Create a feature branch for your work:
39-
```bash
40-
git checkout -b my-feature
41-
```
42-
</Step>
43-
</Steps>
44-
45-
## Development
46-
47-
### Common Commands
6+
## Set up the repository
487

498
```bash
50-
bun install # Install all dependencies
51-
bun run dev # Start the studio (composition editor + live preview)
52-
bun run build # Build all packages
53-
bun run --filter '*' typecheck # Type-check all packages
9+
git clone https://github.com/YOUR_USERNAME/hyperframes.git
10+
cd hyperframes
11+
bun install
12+
bun run build
5413
```
5514

56-
### Studio Editing Work
15+
HyperFrames uses Bun for workspace operations. Do not add a `pnpm-lock.yaml` or replace `bun.lock`.
5716

58-
If you are changing Studio's visual editing surface, read
59-
[Studio Manual DOM Editing](/contributing/studio-manual-dom-editing) before
60-
editing code. The inspector intentionally exposes only interactions it can
61-
persist safely back to HTML, so changes should preserve the capability gates,
62-
source patching model, and documented limitations.
63-
64-
### Running Tests
65-
66-
<CodeGroup>
67-
```bash Core
68-
bun run --filter @hyperframes/core test
69-
```
70-
```bash Engine
71-
bun run --filter @hyperframes/engine test
72-
```
73-
```bash Runtime Contract
74-
bun run --filter @hyperframes/core test:hyperframe-runtime-ci
75-
```
76-
```bash Producer (Docker)
77-
cd packages/producer && bun run docker:build:test && bun run docker:test
78-
```
79-
</CodeGroup>
80-
81-
### Running All Tests
17+
Start Studio while working on UI or composition behavior:
8218

8319
```bash
84-
bun run --filter '*' test
20+
bun run dev
8521
```
8622

87-
## Packages
88-
89-
| Package | Path | Description |
90-
|---------|------|-------------|
91-
| [`@hyperframes/core`](/packages/core) | `packages/core` | Types, HTML generation, runtime, linter |
92-
| [`@hyperframes/sdk`](/packages/sdk) | `packages/sdk` | Headless composition editing engine |
93-
| [`@hyperframes/engine`](/packages/engine) | `packages/engine` | Seekable page-to-video capture engine |
94-
| [`@hyperframes/player`](/packages/player) | `packages/player` | Embeddable composition player |
95-
| [`@hyperframes/producer`](/packages/producer) | `packages/producer` | Full rendering pipeline (capture + encode) |
96-
| [`@hyperframes/shader-transitions`](/packages/shader-transitions) | `packages/shader-transitions` | WebGL shader transition engine |
97-
| [`@hyperframes/aws-lambda`](/packages/aws-lambda) | `packages/aws-lambda` | AWS Lambda distributed rendering adapter |
98-
| [`@hyperframes/gcp-cloud-run`](/packages/gcp-cloud-run) | `packages/gcp-cloud-run` | GCP Cloud Run distributed rendering adapter |
99-
| [`@hyperframes/studio`](/packages/studio) | `packages/studio` | Composition editor UI |
100-
| [`hyperframes`](/packages/cli) | `packages/cli` | CLI for creating, previewing, and rendering |
101-
| `@hyperframes/sdk-playground` (private) | `packages/sdk-playground` | Local SDK playground app |
23+
Studio listens on `http://localhost:5190` when run from the monorepo.
10224

103-
## What to Work On
25+
## Check your change
10426

105-
Not sure where to start? Here are some ideas:
27+
Run the smallest relevant test while iterating, then the repository gates before opening a pull request:
10628

107-
- **Good first issues** — look for issues labeled `good first issue` on GitHub
108-
- **Documentation** — improve docs, add examples, fix typos
109-
- **Linter rules** — add new rules to catch more composition mistakes
110-
- **Examples** — create new starter examples
111-
- **Bug fixes** — check the issue tracker for reported bugs
112-
113-
## Pull Requests
114-
115-
### Commit Format
29+
```bash
30+
bun run lint
31+
bun run format:check
32+
bun run --filter '*' typecheck
33+
bun run test
34+
```
11635

117-
Use [conventional commit](https://www.conventionalcommits.org/) format for all commits and PR titles:
36+
For a composition or registry item, also run:
11837

38+
```bash
39+
npx hyperframes lint
40+
npx hyperframes check
11941
```
120-
feat: add timeline export
121-
fix: resolve seek overflow at composition boundary
122-
docs: add GSAP easing examples
123-
refactor: extract frame buffer pool into shared module
124-
test: add regression test for nested composition timing
125-
```
126-
127-
### CI Requirements
12842

129-
All of the following must pass before your PR can be merged:
43+
The pre-commit hooks format staged files and run checks for the files you changed.
13044

131-
- **Build** — `bun run build` succeeds
132-
- **Type check** — `bun run --filter '*' typecheck` reports no errors
133-
- **Tests** — all test suites pass
134-
- **Semantic PR title** — PR title follows conventional commit format
45+
## Work in the right package
13546

136-
### Review Process
47+
| Surface | Package or directory |
48+
| --- | --- |
49+
| Composition parsing, runtime, types | `packages/core` and `packages/parsers` |
50+
| Browser frame capture | `packages/engine` |
51+
| Encoding and audio/render orchestration | `packages/producer` |
52+
| Command line | `packages/cli` |
53+
| Browser editor | `packages/studio` and `packages/studio-server` |
54+
| Embeddable player | `packages/player` |
55+
| Headless editing API | `packages/sdk` |
56+
| AWS and GCP distributed rendering | `packages/aws-lambda` and `packages/gcp-cloud-run` |
57+
| Reusable blocks and snippets | `registry` |
58+
| Agent instructions | `skills` |
13759

138-
- PRs require at least 1 approval from a maintainer
139-
- Keep PRs focused — one feature or fix per PR
140-
- Target alpha-only PRs at `next` instead of `main`; see
141-
[Release channels](/contributing/release-channels) for branch policy details
142-
- Include a clear description of what changed and why
143-
- Add tests for new features and bug fixes
60+
For Studio changes, verify the behavior in the browser and preserve the source-patching and capability-gate contracts described in the [Studio docs](/studio/index).
14461

145-
## Reporting Issues
62+
## Pull request requirements
14663

147-
- Use [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for bug reports and feature requests
148-
- Search existing issues before creating a new one
149-
- For bug reports, include:
150-
- Steps to reproduce
151-
- Expected behavior vs. actual behavior
152-
- Hyperframes version (`npx hyperframes info`)
153-
- Operating system and Node.js version
64+
- Keep the change focused and explain the user-visible reason for it.
65+
- Add or update tests when behavior changes.
66+
- Use a conventional PR title such as `fix: preserve audio after seeking`.
67+
- Run formatting, lint, typecheck, and relevant tests.
68+
- Include screenshots or a short capture for visual changes.
69+
- Target prerelease-only work to the branch described in [Release channels](/contributing/release-channels).
15470

155-
## Community
71+
Use [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for bugs and proposals. A useful bug report includes the smallest reproduction, the first exact error, `npx hyperframes info`, and the operating system.
15672

157-
<CardGroup cols={2}>
158-
<Card title="GitHub Issues" icon="github" href="https://github.com/heygen-com/hyperframes/issues">
159-
Report bugs, request features, and discuss ideas.
160-
</Card>
161-
<Card title="Code of Conduct" icon="handshake" href="https://github.com/heygen-com/hyperframes/blob/main/CODE_OF_CONDUCT.md">
162-
Our community standards and expectations.
163-
</Card>
164-
</CardGroup>
73+
By contributing, you agree that your work is licensed under the [Apache 2.0 License](https://github.com/heygen-com/hyperframes/blob/main/LICENSE) and follows the [Code of Conduct](https://github.com/heygen-com/hyperframes/blob/main/CODE_OF_CONDUCT.md).
16574

166-
## License
75+
## Related topics
16776

168-
By contributing, you agree that your contributions will be licensed under the [Apache 2.0 License](https://github.com/heygen-com/hyperframes/blob/main/LICENSE).
77+
- [Test local CLI changes](/contributing/testing-local-changes)
78+
- [Contribute a Catalog item](/contributing/catalog)
79+
- [Understand release channels](/contributing/release-channels)

0 commit comments

Comments
 (0)