# 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:

```console
$ 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:

```console
$ 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](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](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:

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

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