Contributing
Thank you for your help with Protota — a mockup tool for Adwaita app UIs that obeys the GNOME HIG. Protota renders GTK4/Libadwaita from a typed widget tree using real @gjsify/adwaita-web components, so mockups look and behave like real Adwaita.
Contribute compute — no code needed
Your machine runs one task at a time using your signed-in AI coding CLI. The relay alternates between eligible School (OS) and Reef (apps) hives after each task. If one hive has no work, the other can continue.
The guide covers prerequisites, verified just setup, credentials, provider costs, and how to stop with Ctrl+C. Your subscription quota or API charges apply. Never post account credentials or API keys in issues or pull requests.
Before you start
- CONTEXT.md — the document of decisions: vision, tech foundation (pure browser webapp, no GJS/Node runtime), and the
MockupDocumentmodel. - AGENTS.md — how to work in this repo as an agent: renderer contract, verification, CI status, and merge rules.
- docs/components.md — every component that Protota can build with. For each one: its GTK export class, named slots, editable properties, and legal children. A script makes it from the code, so it cannot drift.
Project layout
| Path | What lives here |
|---|---|
src/ | The app: widget tree, renderer, presets, Blueprint/GtkBuilder import/export |
presets-src/ | Preset source files |
docs/ | components.md (generated component catalog), spec/ (vendored GNOME HIG/spec snapshot), and other docs |
tests/ | Playwright browser tests (E2E); unit conformance tests live in src/__tests__/ |
public/ | Static assets |
scripts/ | Build and maintenance scripts |
Development
npm install
npm run dev # Vite dev server
npx tsc -b # TypeScript typecheck — CI runs this on every PR (not docs-only)
npm run lint # oxlint
npm run build # Production build → dist/
npm run test:unit # Blueprint/renderer conformance tests
npm test # Playwright tests
just check runs lint, unit tests, and build together.
The renderer is generic: presets must not add branches for one app. An import of Blueprint or GtkBuilder keeps the tree structure and the properties that Protota supports. The import must report each unknown visual widget, so that a contributor can add support for it on purpose. It must never drop a widget silently.
Making a change
-
Branch from
main— descriptive name, e.g.git checkout -b fix/import-errororfeat/preset-sidebar. -
Keep commits focused and sign them with DCO:
git commit -s(each commit carries aSigned-off-bytrailer). -
Run the checks before you push:
npx tsc -b # typecheck — its own CI step, see #211npm run lint # oxlintnpm run test:unit # conformance testsnpm run build # production build must succeednpm test # Playwright browser testsRun
npx tsc -bfirst:npm run buildistsc -b && vite build, so it typecheckssrc/**(includingsrc/__tests__) but not thetests/**Playwright specs — neither command catches a type error in a spec. -
Open a PR. Tell what changed and why, and link any related issue.
If you touch the renderer or presets
- Keep the renderer generic (see above).
- Re-generate
docs/components.mdif the component catalog changed. - Add conformance coverage in
src/__tests__/for any new widget or property; browser behaviour belongs intests/.
If you change docs
- User-facing behavior belongs in
docs/and the README. - A script makes the component catalog — edit the source, not the output file.
Code of conduct
Be respectful and constructive — see CODE_OF_CONDUCT.md (Contributor Covenant 2.1).
Questions?
Open an issue. CONTEXT.md is the authoritative reference for design decisions; AGENTS.md covers the renderer contract and how to work in this repo.