Contributing to zig-openuri #

Issues and pull requests go to the Tangled mirror, https://tangled.org/jcollie.dev/zig-openuri.

Setting up #

Everything the project builds with comes from the Nix flake:

$ nix develop

That shell has Zig 0.17, dbus-daemon for the portal tests, reuse, and kcov.

Before sending a change #

CI runs these, and a change should pass them all:

$ reuse lint
$ zig fmt --exclude zig-pkg --check .
$ zig build test --summary all
$ zig build check --summary all

zig build check compiles the library and the command for Linux, Windows and macOS on x86_64 and aarch64 without linking them. It is the only automatic proof that the Windows and macOS code still compiles, since CI runs on Linux. It cannot prove that the code works there. A change to src/windows.zig or src/macos.zig needs a run of zig build run -- https://example.com/ on that platform. Say in the pull request that you did it.

How the code is laid out #

• src/root.zig is the public API: open, openWithConnection, Options, Outcome and the error set. Every open request goes through the checks in src/uri.zig before it reaches a platform.
• src/uri.zig holds the scheme checks and the decoding of a file: URI into a path. It needs no full URI parser on purpose.
• src/linux.zig, src/windows.zig and src/macos.zig each hand the URI to that platform's opener and map the result onto the library's errors.
• src/main.zig is the openuri command.
• tests/portal_test.zig runs the Linux code against a fake portal on a private bus. Behavior that depends on the portal's replies is tested there rather than with mocks.
• tools/docs_server.zig serves the generated documentation for zig build docs-serve.

Vocabulary and decisions #

GLOSSARY.md fixes the words the code and documentation use. For example, it says handler rather than "browser" or "default app". Use those words, and add a term there when a new concept appears.

Decisions that would surprise a reader are recorded in docs/adr. Read them before changing what they cover. In particular, do not add an xdg-open fallback, and do not relax the scheme checks, without a new ADR that supersedes the old one.

Licensing #

New files carry an SPDX header:

// SPDX-FileCopyrightText: © 2026 Your Name <you@example.com>
// SPDX-License-Identifier: MIT

Files that cannot hold a comment are covered in REUSE.toml.