punktfunk/CONTRIBUTING.md

Contributing to Punktfunk

Thanks for your interest in contributing!

Licensing of contributions (inbound = outbound)

Punktfunk is dual-licensed under MIT OR Apache-2.0.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as MIT OR Apache-2.0, without any additional terms or conditions.

By opening a pull request you agree to license your contribution under these terms. This is the standard Rust-ecosystem "inbound = outbound" model; it keeps the project's licensing unambiguous (including the Apache-2.0 §5 contributor patent grant) and any future relicensing clean. You retain the copyright to your contributions.

Do not paste copyleft (or otherwise incompatibly-licensed) code

The single thing that could poison the permissive license is copied source from a copyleft project. Several adjacent projects (Sunshine, Apollo, Moonlight) are GPL-3.0. You may study them and reimplement a technique, protocol, or wire format — those are not copyrightable — but never paste their code, and do not translate a GPL implementation line-by-line. When a comment credits prior art, make clear it is an independent reimplementation, not a copy. The same applies to any third party's code under a license incompatible with MIT/Apache.

If you add a new third-party dependency, it must be permissive (MIT / Apache-2.0 / BSD / ISC / Zlib / Unicode-3.0 / etc.). about.toml holds the accepted-license allow-list; regenerate the attribution file with scripts/gen-third-party-notices.sh when the dependency tree changes.

Prerequisites

The Rust toolchain is pinned exactly in rust-toolchain.toml; rustup installs it for you the first time you build, so don't override it — a different rustc reformats files nobody touched.

The workspace links real system libraries, so a bare cargo build --workspace fails on a stock machine. The authoritative list is what CI installs, in ci/rust-ci.Dockerfile — on Ubuntu 26.04:

sudo apt install build-essential clang libclang-dev pkg-config cmake \
  libpipewire-0.3-dev libopus-dev libwayland-dev libxkbcommon-dev \
  libgl-dev libegl-dev libgbm-dev \
  libgtk-4-dev libadwaita-1-dev libsdl3-dev \
  libvulkan-dev

(The last two groups are the Linux client shell and the Vulkan session presenter; skip them only if you never build those crates. libvulkan-dev is for the LOADER's pkg-config/soname — ash dlopens it. Nothing in the workspace links FFmpeg, so no libav*-dev appears here. scripts/bootstrap-ubuntu.sh sets up an Ubuntu capture-test host — NVIDIA, Sway, PipeWire — and is not a substitute for the list above.)

Before you push

Enable the repo git hooks once per clone — they run the cheap gates CI runs (rustfmt for the main and UMDF driver workspaces, Biome, writing style, unsafe hygiene) on every commit and push, so a push can never fail CI on those alone:

git config core.hooksPath scripts/git-hooks

On commit the hook formats your staged Rust and JavaScript and re-stages the result; a file that carries both staged and unstaged edits is refused rather than rewritten, so an unstaged edit is never swallowed. On push nothing is rewritten — the commits already exist, so it only reports, and each failure prints the command that fixes it. The Biome gate is skipped where web/ or plugin-kit/ has no node_modules — bun install in either directory to get it locally.

Then the usual full pass. Use --locked as CI does — otherwise a silent Cargo.lock update can pass locally and fail CI:

cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test  --workspace --locked

Two more gates that only apply to some changes:

• Touched web/ or docs-site/? CI builds and typechecks both. Run, in that directory:

  bun install && bun run build && bun run lint
  

  Build first — it generates the API client / MDX typegen that the typecheck imports.
• Touched Windows- or Linux-gated code from another OS? scripts/xcheck.sh windows (or linux) type-checks and lints that platform's #[cfg(target_os = …)] code in about a second, instead of waiting for the CI job that compiles it.

Generated artifacts are checked in. include/punktfunk_core.h (cbindgen) is regenerated by the build and CI fails if the committed copy drifts. api/openapi.json is gated the same way: the rust job regenerates the spec and diffs it against the committed file, the docs-drift job checks that docs-site/public/openapi.json — the snapshot the docs site serves — is a byte-for-byte copy of it, and sdk-plugin-kit regenerates the SDK's TypeScript client from it. Touch the management API and CI stays red until you regenerate all three:

cargo run -p punktfunk-host -- openapi > api/openapi.json
cp api/openapi.json docs-site/public/openapi.json
(cd sdk && bun run gen)

Getting the expensive CI lanes to run

Open the pull request as a draft while you iterate — in Gitea that is the WIP: title prefix. A draft runs only the cheap gates: writing style, docs drift, secret scan, and the plugin-kit and Decky typechecks. Seconds of fleet time instead of an hour.

Mark it ready for review to turn on rust, rust-arm64, web and docs-site. To get them on a pull request you want to keep as a draft, add the ci:all label instead.

Neither of those starts a run by itself on Gitea 1.27 — measured, not assumed — so after marking ready or labelling, either push again or hit Re-run on the latest run in the Actions tab. The gate reads the pull request's state at that moment, so the re-run picks up the change.

Platform builds

Android, Apple, the Windows client and drivers, the Windows setup test and the Nix flake are label-only. Being ready for review is not enough — they cost too much to run on every pull request:

Label	Runs
ci:android	the Android build, and publishes its APK (below)
ci:apple	the Apple client build and tests
ci:windows-client	the Windows client
ci:windows-host	the Windows drivers and the setup test
ci:nix-rust	the Nix flake
ci:all	all of the above, plus the lanes above

Only someone with write access can add a label, which is what keeps these off the persistent signing runners for untrusted code. Each job also keeps its own fail-closed fork check.

Installing the Android build from a pull request

A pull request labelled ci:android attaches its debug APK to the run, as a zip you can download in one click from the run page. That is the existing Attach APK(s) to the workflow run step; the label is now what makes the build happen at all, so it is also what produces the APK.

It is debug-signed, so it installs alongside a store build rather than replacing it.

Push to main always runs everything, so nothing escapes verification — it moves to merge time. The platform workflows (Android, Apple, Windows, Nix, packaging) are unaffected here: they are already narrowed by path, so they fire only when their own files change.

Where facts live (docs vs READMEs vs website)

Every user-facing fact has exactly one canonical home; everything else links to it. Duplicated walkthroughs are how the docs drifted before — don't add new ones.

Surface	Owns	Never contains
docs-site (docs-site/content/)	All user-facing facts: install, config, features, troubleshooting	Design rationale
READMEs (root, packaging/*, scripts/*)	Dev/packager rationale and pointers into the docs	User walkthroughs duplicated from docs-site
punktfunk.unom.io (separate repo)	Marketing, downloads, blog	Instructions — it deep-links the docs instead
punktfunk-planning (private)	Design rationale, RFCs, plans	Anything user-facing

Docs pages are written for one of two audiences, not both at once: the get-started track (quickstart, install, pairing — short, one task per page, happy path only) assumes no Linux expertise; the reference track (configuration, CLI, API, per-compositor pages) is allowed to be dense. When a change touches a user-facing fact, update the docs-site page that owns it in the same PR.

CI enforces the cheap half of this (scripts/ci/check-docs-drift.sh, check-docs-links.sh, and check-writing.sh): the OpenAPI snapshot must match api/openapi.json, the docs-site copy of data/platforms.json must match the canonical one, scripts/install.sh must carry the file's install lines verbatim, every PUNKTFUNK_* variable the docs mention must still exist in the tree, the counts of undocumented PUNKTFUNK_* variables and undocumented punktfunk-host subcommands may never grow (document the new knob, or consciously raise the baseline in the script), and internal docs links must resolve.

Match the surrounding code's comment density and naming.

See the README's Build & test section for the extra dev commands (the FEC loss harness, the standalone C-ABI proof) and Design invariants for the rules a change is expected to hold to, and the docs site for architecture and per-platform guides.

How to write it (commits, changelog, comments)

House style lives in docs/writing.md, which also carries a per-PR checklist. The three rules you need before your first commit:

• Commit subjects follow Conventional Commits — type(scope): summary, 72-character cap, imperative, no trailing period. The why goes in the body, wrapped at 72, 200 words max. The investigation goes on the pull request, not in the message. A Gitea PR title becomes the merge subject, so write the PR title as a conventional commit too. scripts/ci/check-writing.sh fails the PR if a commit on it breaks this.
• Release notes are written at version bump, not on every PR. docs/releases/vX.Y.Z.md is the human page. CHANGELOG.md is a version table plus Breaking plus Knobs. Do not add a CHANGELOG bullet on a feature PR. If the reader must act, add a BREAKING CHANGE: footer on the commit. Rules: docs/writing.md §2.
• A comment states an invariant or a trap, not a recap of the diff. Present tense: the live rule, not the archaeology of old versions and not a poem. // is four lines (CI fails at six); a module //! is 8–20 (CI fails at 24). Length is a backstop. If a trust boundary matters, a type, test or assertion has to enforce it — a comment alone never does.