Developers

How we work: the gates

A change lands when CI says so. This page lists what CI checks, how to run the same checks yourself first, which files are generated and how to regenerate them, and how tests, ADRs, and the roadmap are kept.

The rules

  • Done means the acceptance criteria pass in CI, clippy is clean, the docs are updated (the user docs under docs/ and the matching page on this site), the OpenAPI document is regenerated if the API changed, and the roadmap box is ticked. That is AGENTS.md's rule 10, and the rest of this page is how to meet it.
  • Say what you did not check. A task's Done note in the roadmap names what was verified and what was not (a cluster you did not run, an architecture you did not test). A later reader trusts the note.
  • Never edit a generated file by hand. Change its source and regenerate. CI fails on drift.

What CI runs

JobWhat it catches
fmt, clippyFormatting, and clippy with warnings denied. The project enables the pedantic lints, so a function over 100 lines, a struct with more than three bool fields, or two variables with similar names fails the build.
testThe whole workspace, on x86-64 and on arm64 (an arm-only timing flake has been seen).
denycargo-deny: advisories, licences, banned crates, sources. An advisory can be ignored in deny.toml only with a reason written beside it, and only for something that is not a vulnerability to us (an unmaintained crate we use only to read tokens, say).
bench-smokeThe benchmark harness, end to end (make bench-smoke). Hosted runners are too noisy for the 5% regression gate, which needs a fixed machine, so CI fails only on lost queries or errors: judging speed is your job. See Size and performance budgets.
siteThis site builds, every link and asset resolves, and the pages generated from the repo (the configuration reference, the architecture page) agree with it. The same job checks that the Grafana dashboard is current, and that every P0 requirement has a test or evidence and docs/v1-requirements.md is current (spec/trace.py --check).
ui, oidcThe UI's API types match the OpenAPI document (a diff fails), the OpenAPI document passes the agent-readiness lint (.spectral.yaml), svelte-check with warnings failing, every "?" in the UI has a help topic, the build stays within the 400 KiB budget, and the Playwright suite passes against the real binary. oidc runs the suite against real Keycloak and Authentik. See Write UI tests.
helmThe chart lints and installs on kind (amd64) and k3d (arm64), DNS works through a LoadBalancer with the client's address in the query log, and the alert rules fire on bad values and stay quiet on good ones.
nativeThe Pi and Linux paths on a disposable runner (the Compose bundle, the installer and its systemd unit), and the end-to-end cluster scripts under deploy/cluster/ on real processes. See Extend the cluster protocol.
migrationThe importers against the real Pi-hole and Technitium images, backup and restore across two nodes, agent tokens, and the MCP server end to end.
image (own workflow)Builds every platform, enforces the 15 MiB size limit, runs a smoke test of each image, then publishes edge.
codeql, fuzz, pagesCode scanning, the nightly fuzzers, and the publishing of this site.

On your machine

Run the cheap checks before you push; a CI round trip costs minutes.

make check                      # fmt, clippy, test, deny
make bench-smoke                # before you finish a change to the DNS path

cd ui
npm run check                   # svelte-check, warnings fail
npm run check:help              # every help button has a topic, and the reverse
npm run build                   # also enforces the 400 KiB budget
npm run test:e2e                # the Playwright suite (needs a built binary)

Run the heavy parts on a build machine. A full workspace test and the Playwright suite take real memory and minutes. Use whatever fast Linux box you have for them; the repository does not assume one.

Generated files

These are written by tools, committed, and checked for drift. Change the source column, regenerate, commit both.

FileMade fromRegenerate
docs/api/openapi.jsonThe utoipa annotations and the models in crates/wrendns-apiUPDATE_OPENAPI=1 cargo test -p wrendns-api api_001_committed_openapi
docs/api/mcp-tools.jsonThe tool definitions in crates/wrendns-api/src/mcp.rsUPDATE_MCP=1 cargo test -p wrendns-api agt_006_committed
ui/src/lib/api-types.tsdocs/api/openapi.jsoncd ui && npm run types
docs/config-schema.json, and the configuration referenceThe doc comments in crates/wrendns-config/src/schema.rsUPDATE_SCHEMA=1 cargo test -p wrendns-config doc_002_committed_schema
docs/v1-requirements.mdThe requirement IDs in code and test names, the roadmap, and spec/trace-evidence.tomlpython3 spec/trace.py (--check verifies)
The Grafana dashboard and the alert rulesThe generators under deploy/grafana and deploy/prometheuspython3 deploy/grafana/build.py, bash deploy/prometheus/build.sh (--check verifies)
ui/src/lib/icons/brands.ts, map.data.tsThe curated list and the two icon packsSee Extend the domain icons

Regenerate the requirements trace last. It reads what the other generators wrote, so after you change an API or a test name, python3 spec/trace.py --check can say the file is stale even though you ran it earlier. Run it again, then re-run the gate.

Tests and names

  • A Rust test is named <requirement>_<number>_what_it_checks, for instance api_004_disable_local_login_keeps_a_break_glass_admin. A Playwright test title starts with the ID: obs_039 domain icons.
  • The code carries the ID where the requirement is implemented: // REQ: API-004 — …. The trace reads both, so a requirement with no test and no comment shows up as unproven in docs/v1-requirements.md.
  • A test compares with something independent. The query-log negation tests compare each search with a scan of every row; the cluster tests check that no real name survives in a part. A test that repeats the code's own logic proves little.
  • Write the test that fails first. For a bug, put the broken code back and watch the new test fail before you trust it (the two-factor fix was checked this way).

ADRs and the roadmap

  • An ADR is an entry in spec/11-decisions.md, newest first, with its status in the heading: (Proposed) or (Accepted). You propose; the owner accepts. It records the context, the decision, the alternatives you rejected, and the numbers behind the choice.
  • Two branches that each add an ADR conflict at the top of the list. Keep both, the higher number first, and renumber yours if the other landed first.
  • The roadmap is spec/10-roadmap-and-tasks.md: a milestone, then tasks like T24.1 with their acceptance criteria, a Done note, and an Open note for what is left or waiting for the owner. Tick a task when its criteria pass, not before.
  • User-visible behaviour gets user docs in docs/ and the matching page here, and a requirement in spec/01 if it is new.

A flaky test

A test that fails once and passes on a re-run is a bug in the test or the code, not noise.

  • Re-run only the failed job to get a green run, and say that you did.
  • Open an issue with the run, the assertion, and your theory, as #69 does for two UI tests. A test that cannot be trusted hides real failures.
  • The Playwright suite runs with no retries on purpose: one failure in the serial group would otherwise make a retry fail somewhere else and hide the cause. See Write UI tests.

Before you push

  1. The criteria pass and you can say how you checked each.
  2. The gate is green on your machine: make check, the UI checks if you touched the UI, make bench-smoke if you touched the DNS path.
  3. Generated files are regenerated, the trace last.
  4. Docs and the roadmap are updated, with what you did not verify.
  5. The budgets hold: see Size and performance budgets.