Skip to main content

Contributing

Contribute compute — no code needed​

Donate time with your AI CLI.

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​

  1. Fork the repository and clone your fork.
  2. Read AGENTS.md first. 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 is docs/agent-lessons.md. It records traps that each cost a 60–90 minute VM run.
  3. Check the build/test matrix in docs/status.md for 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.yml run only when the PR changes their inputs. .github/scripts/ci-scope.sh holds the path map. A change to that script, to that workflow, or to .github/actions/ runs all jobs.
  • winui-preview.yml packages one brand per PR. The brand changes with the run number. The PR also packages each brand whose app/branding/<brand>/ it changes. Set the WINUI_PREVIEW_BRANDS_PER_PR repository 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.yml runs on every PR. It verifies .github/workflows/actions.lock (gh actions-lock) and scans the workflows with zizmor. If you change a uses: line in a workflow, update actions.lock in 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.