Contributing
Thank you for your interest in this project! It is part of the TunaOS ecosystem.
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 repo and clone it locally.
- Install the Go version declared in
go.modand thejustcommand runner. - Read the project README, user guide, and architecture overview.
- Open an issue to discuss your change before you submit a PR.
Validate Your Changes
Run the fast checks used for every pull request:
just check
just build
go vet ./...
go test -tags=integration -run='Help' ./...
You can format Go files with just fmt.
If you change an example or fixture recipe, make sure that every JSON file still parses:
for recipe in examples/*.json fixtures/*.json; do
python3 -m json.tool "$recipe" >/dev/null
done
Media builds and boot tests need more host tools, elevated privileges, and
substantial disk space. Run the relevant script under scripts/ when your
change affects the image, bootloader entries, or live boot path. The
pull-request CI runs the broader smoke suite.
Pull Requests
- Keep PRs focused — one change per PR.
- Follow the existing code style and conventions.
- Update docs if your change affects usage.
- Include the validation commands you ran in the PR description.
Versioning and Releases
Use Conventional Commits for commits and squash-merge PR titles:
feat:adds a feature and bumps the minor version.fix:fixes a bug and bumps the patch version.feat!:or aBREAKING CHANGE:footer marks an incompatible change. Before 1.0, this bumps the minor version; from 1.0 onward, it bumps the major version.
Release-please runs on pushes to main and opens a release PR with the
version manifest and changelog. The first release is v0.1.0. A maintainer
adds docs/releases/<tag>.md to the release PR, then merges it to create
the tag and a draft GitHub Release. The repository must allow GitHub Actions
to create pull requests.
The release-please workflow then calls the binary and container publishers
with that tag. These calls let the publishers run because tags created with
GITHUB_TOKEN do not trigger other workflows. No personal access token is necessary.
GoReleaser builds static Linux amd64/arm64 tarballs and SHA-256 checksums
with a read-only token. A separate job verifies the checksums and release
notes, then uploads all assets together before it makes the draft public.
It preserves release-please's notes. Each binary reports its version with
tacklebox --version.
The container workflow publishes both v0.1.0 and 0.1.0 style tags to GHCR,
as well as the existing latest and commit tags.
Tag pushes from maintainers also run the publishers. To test binary archives
without a release, run goreleaser check and
goreleaser release --snapshot --clean, or dispatch the binary workflow on a
branch. A manual run on a tag uploads assets to that release.