Developers

Working on WrenDNS

Some parts of WrenDNS are extended in one way only: a brand for the domain icons, a parameter on the API, a read between cluster nodes. These pages write that way down, with the reasons, so a person or an AI agent can extend it correctly the first time.

Start here

The spec is the source of truth. Read AGENTS.md first: it says what to read, in what order, and what "done" means. Then the section of spec/ for your task, and its entry in the roadmap (spec/10).

  • Work task by task. Restate the task's requirement IDs and acceptance criteria before you start, and tick the box when they pass.
  • Where the spec is silent, don't invent. Choose the most conservative option, record it as an ADR with status Proposed in spec/11, and list it for the owner. The Decisions page lists them all.
  • Trace everything. Requirement IDs go in code comments at the place they are implemented, in test names, and in commit messages.

The principles behind the rules

Every page here applies the same few ideas. When a rule on a page seems arbitrary, it is one of these.

PrincipleWhat it means in practice
Performance, then footprintThe owner's order is performance, lightweight footprint, observability, deployability, clustering, protocols, and last UI polish. Nothing is added to the query path without a benchmark, and the image has a hard size limit. See Size and performance budgets.
DNS never depends on anything elseTelemetry, storage, the API, and the cluster can fail without a query going unanswered. A new feature reads and writes off the query path, with a deadline.
Measured, not assumedA size or speed claim comes with a number from a real build, and a speed claim from a benchmark with a control. The ADRs record the numbers.
Generated files are generatedThe OpenAPI document, the MCP tool list, the UI's API types, the configuration schema, and the requirements trace are written by tools and checked for drift. You change the source and regenerate. See How we work: the gates.
Nothing leaves unredactedThe UI fetches nothing from other sites, the content security policy says so, and a support package is redacted on the node it came from. A feature that moves data between nodes or out of the page has to say what it carries.
Fail closed, fail loudlyAn unclassified setting is removed from a support package and a test fails; an older node that doesn't know a request is listed as missing instead of answering wrongly; a flag without its filter is refused with a message that names it.

The pages

How we work

Extend

The web UI

How each page is laid out

  1. The rules. What we insist on, and why. If you need to break one, write an ADR first.
  2. The recipe. The steps to extend it, in order, with the files you touch.
  3. The checks. Which test or gate fails when you get it wrong, so you know a green run means something.
  4. A worked example. A real change, with what went wrong on the way, because that is where the rules came from.

Not written up yet

These areas also have a fixed way of doing things, but no page. They are written up the same way when someone needs them:

  • The presets under presets/ (upstreams, services, safe search) and how a service's domains are chosen.
  • Redaction and the configuration classification table behind the support package: every setting must have a class, and a test fails when one doesn't.
  • The Grafana dashboard and the alert rules, which are generated and checked for drift.
  • The Helm chart's values and its end-to-end tests.

Where to look meanwhile: the architecture page for how the crates fit together, Decisions for why, the releasing guide, and the standards we implement.