enricobuehlerandClaude Opus 5
d383161723
ci / rust (push) Failing after 2m31s
ci / docs-site (push) Successful in 1m22s
ci / web (push) Successful in 1m48s
docker / builders (--build-arg FEDORA_VERSION=44, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm, -f44) (push) Successful in 1m1s
ci / rust-arm64 (push) Successful in 2m2s
docker / builders (ci/android-ci.Dockerfile, punktfunk-android-ci) (push) Successful in 11s
docker / builders (ci/arch-ci.Dockerfile, punktfunk-arch-ci) (push) Successful in 9s
docker / builders (ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 9s
docker / builders (ci/rust-ci-noble.Dockerfile, punktfunk-rust-ci-noble) (push) Successful in 9s
docker / builders (ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 9s
docker / builders-arm64cross (push) Successful in 20s
docker / apps (., web/Dockerfile, punktfunk-web) (push) Canceled after 36s
docker / apps (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Canceled after 36s
docker / deploy-docs (push) Canceled after 0s
~1150 feat/fix commits landed since v0.19 and the docs drifted badly. This is a full sweep of every page against the code as shipped: ~280 verified corrections, nine new pages, and one deletion. The worst of what was wrong: the quickstart's five-minute path could not work (`serve` never started the web console, so step 3 had no PIN to read); every packaged Linux host runs `serve --gamestream` while security.md told readers to leave GameStream off; HDR was documented as Windows-only; `PUNKTFUNK_SECURE_DDA` was documented as a working knob that nothing reads; `PUNKTFUNK_INPUT_BACKEND` listed a `uinput` value that does not exist and named libei for KDE instead of kwin; README linked three pages deleted on 2026-07-05; and the rpm-ostree update command pointed at a script no package installs. Completeness: about half of what shipped since v0.19 had no page at all. New: support-matrix (what works where, from 217 verified capability cells), input (mouse/touch/pen — and the in-stream chords, so the docs finally say how to get your mouse back), client-settings, profiles-and-links, game-library, clipboard, wake-on-lan, hdr, uninstall. Updating existed but had zero inbound links. status.md is gone: its facts moved into the support matrix, its shell stays as a redirect so the public URL does not 404. roadmap.md is themes now, not a feature checklist — checkboxes are what rotted. Debian is no longer claimed. The .deb's Depends resolve against Ubuntu images, nothing in CI builds or tests Debian, and Debian 12 is below the glibc 2.39 floor. The `debian` in the repo URL is the package format. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
100 lines
4.6 KiB
Markdown
100 lines
4.6 KiB
Markdown
# 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**,
|
|
which is what gets you FFmpeg 8:
|
|
|
|
```sh
|
|
sudo apt install build-essential clang libclang-dev pkg-config cmake \
|
|
libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libavfilter-dev libavdevice-dev \
|
|
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 `pf-ffvk`; skip them only if you never build
|
|
those crates. `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 exact rustfmt gates CI runs (main
|
|
workspace + the UMDF driver workspace) on every commit and push, so a push can never fail CI
|
|
on formatting alone:
|
|
|
|
```sh
|
|
git config core.hooksPath scripts/git-hooks
|
|
```
|
|
|
|
Then the usual full pass. Use `--locked` as CI does — otherwise a silent `Cargo.lock` update can pass
|
|
locally and fail CI:
|
|
|
|
```sh
|
|
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:
|
|
```sh
|
|
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 **not** gated — nothing in CI
|
|
regenerates or diffs it, so regenerate and commit it yourself whenever you touch the management API,
|
|
and copy the snapshot the docs site serves:
|
|
|
|
```sh
|
|
cargo run -p punktfunk-host -- openapi > api/openapi.json
|
|
cp api/openapi.json docs-site/public/openapi.json
|
|
```
|
|
|
|
Match the surrounding code's comment density and naming. Commit messages end with the
|
|
`Co-Authored-By` trailer (see `git log`).
|
|
|
|
See the [README's Build & test section](README.md#build--test-from-source) for the extra dev
|
|
commands (the FEC loss harness, the standalone C-ABI proof) and
|
|
[Design invariants](README.md#design-invariants) for the rules a change is expected to hold to, and
|
|
the [docs site](https://docs.punktfunk.unom.io) for architecture and per-platform guides.
|