Contributing
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.
Getting started
- Fork the repository and clone your fork.
- Read
AGENTS.mdfirst. It names the four project layers: Windows OEM, QGA control plane, deployer initramfs, and E2E test runner. It also names the docs to read before you change each layer. One of these docs isdocs/agent-lessons.md. It records traps that each cost a 60–90 minute VM run. - Check the build/test matrix in
docs/status.mdfor known-good and known-red cells. Do this before you blame a symptom on your change.
Building and testing
just --list shows all targets (needs just; the E2E targets also need
podman, qemu-img, and /dev/kvm).
The fast, no-container red-green loop for day-to-day changes:
just test # or: tests/run.sh fast
This runs the bats unit suites (payload gates/transforms) plus go test for
the cross-platform Go packages. Windows-tagged Go (app/*_windows.go) only
builds on Windows by design, so this tier covers the platform-independent
code.
Containerized integration tests (User Data Bridge, WSL, go-native gates) run
in a privileged Fedora container and need podman:
just test-slow # or: tests/run.sh slow
Full hosted E2E (Windows 11 → wootc deployer → native Linux → Windows 11)
runs on dedicated remote hosts. You cannot reproduce it on your own machine.
docs/RELEASING.md tells how matrix cells go green.
What CI runs on a pull request
CI runners are shared by all tuna-os repositories, so a PR runs only the jobs that its change can affect:
- Lint and the fast tier run on every PR.
- The other jobs in
ci.ymlrun only when the PR changes their inputs..github/scripts/ci-scope.shholds the path map. A change to that script, to that workflow, or to.github/actions/runs all jobs. winui-preview.ymlpackages one brand per PR. The brand changes with the run number. The PR also packages each brand whoseapp/branding/<brand>/it changes. Set theWINUI_PREVIEW_BRANDS_PER_PRrepository variable to package more brands.
A push to main uses the same path map on the pushed commits, so each
commit that changes a job's inputs still gets its own run of that job (#363).
A manual dispatch and a nightly schedule run all jobs. winui-preview.yml
also packages all brands each night.
Two other workflows can fail a pull request:
actions-security.ymlruns on every PR. It verifies.github/workflows/actions.lock(gh actions-lock) and scans the workflows with zizmor. If you change auses:line in a workflow, updateactions.lockin the same pull request.ste.yml(Prose) runs when a PR changes Markdown. It checks the prose against Simplified Technical English and fails when the problem count is more than the number in.ste-budget. That budget only goes down: do not raise it to make a PR pass.
Before opening a PR
- Run
just test(fast tier) locally — it's fast enough to run on every change. - Before you change the E2E harness, the deployer, or the runners, read
docs/agent-lessons.md. Those traps are easy to hit again. - Status that comes from a proxy and not from an observable is the most frequent bug class in this codebase. When you add a check, ask what it prints if the asserted thing never occurred. Then break the code and make sure that the test goes red.
License
wootc is dual-licensed under GPL-2.0 and MIT (see LICENSE-GPL-2.0 and
LICENSE-MIT).
Getting help
Questions or stuck? Open an issue, or ask on Matrix #tunaos.