Contributing
Build and test
zig build -Doptimize=ReleaseFast # the app
zig build test # unit tests
tools/qa.sh # the full UI QA, off-screen
tools/membench.sh 50 # RAM and idle CPU per theme, with a budget in MB| Command | What it does |
|---|---|
zig build test | Tests the pure parts: KDL, colors, layout, markdown, Store, built-in themes, settings, protobuf, APNG, media URLs. Doesn't need SDL or a window |
tools/qa.sh | A debug build with safety checks. Runs the general battery, the sign-in screen in both modes, and a battery per theme in light and dark. Screenshots land in qa-out/ |
tools/qa_http_tls.sh | After tools/qa.sh: the plugins' HTTP with real TLS, against a local server with its own certificate. Needs python3 and openssl |
tools/snapshots.sh | Regenerates the README's screenshots in docs/ without opening a window |
tools/membench.sh N | Measures every theme and fails over N MB |
tools/site_shots.sh | Regenerates the website's images |
python3 tools/gen_site.py | Regenerates the website in docs/ |
The QA drives the real UI: it clicks through elements, and a button with no effect counts as a failure. It runs in demo mode, without a window, and never touches your account.
CI (.github/workflows/ci.yml) runs the tests, then builds the app on Arch and runs the full QA on every push and pull request.
Sending a theme
A theme is the easiest way to contribute: one .kdl file and no Zig. zig build test loads every built-in theme and builds its layout, so a new one gets checked automatically. Read Writing themes, especially the design tips at the end.
To add one as built-in, put the file in themes/ and add its name to theme_names in build.zig and to themes/builtin.zig.
Sending code
- Keep the layers apart:
core/knows nothing about windows, and the UI never changes data directly. - Keep it light. Don't add work per frame, per message or per keystroke when nothing is using it, and remember the loop is supposed to sleep.
- Test the pure parts in
zig build test, and add a step to the QA for UI behavior. - Run
tools/qa.shbefore opening a pull request. - Code comments and identifiers in this repository are mostly in Portuguese, so follow the file you're editing.
Documentation
English is the main version and Portuguese is secondary, and both should change together.
| English | Portuguese |
|---|---|
README.md | README.pt-BR.md |
docs/plugins.md | docs/plugins.pt-BR.md |
site/guide/en/*.md | site/guide/pt/*.md |
site/landing.html ({{English||Português}}) | the same file |
The website lives in docs/, and it's generated by tools/gen_site.py from those files and from themes/*.kdl. Theme palettes, options and layouts on the site always come from the real theme files.
Credits
Built with Zig, SDL3, Dear ImGui, dear_bindings, FreeType, fontconfig, libcurl, zlib, libwebp, Opus, stb_image, Lua, libdave and MLSpp. The website uses Departure Mono, JetBrains Mono, Archivo, Fraunces and DM Mono, under the SIL Open Font License.
License
Not decided yet. Third-party code in third_party/ keeps its own license, in each folder's license file.