From f79cd9810743eea50e559f3589d22395006604be Mon Sep 17 00:00:00 2001 From: clawbot Date: Fri, 7 Aug 2026 22:31:48 +0200 Subject: [PATCH] docs: document the no-DNS-mocking policy in README (closes #94) (#95) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a prominent "No DNS mocking. Ever." section near the top of `README.md`, per owner policy (sneak, 2026-08-07): - DNS is never mocked in this project — no mock resolvers, fake DNS servers, or stubbed lookups, in tests or anywhere else. - Tests exercise real iterative resolution against live nameservers by design. - Flaky live tests are fixed with robustness (retries, multiple nameservers, timeouts) or explicit opt-in gating decided by the owner — never with mocks. - Contributions introducing DNS mocks will be rejected. Markdown-only change; matches the README's existing tone and hard-wrap style. `script/fmt` covers Go only, so no formatter output applies to this file. Verified via `script/cibuild` (docker build runs `make check` with the pinned toolchain) — green. A direct local `make check` shows 21 pre-existing `goconst` lint findings that come from a newer local `golangci-lint` (v2.12.2 vs the pinned v2.10.1) and are unrelated to this change. Related: #93 is being reframed under this policy. Co-authored-by: sneak Reviewed-on: https://git.eeqj.de/sneak/dnswatcher/pulls/95 Co-authored-by: clawbot Co-committed-by: clawbot --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index 9ed5805..83f9226 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,26 @@ without requiring an external database. --- +## No DNS mocking. Ever. + +**DNS is never mocked in this project — not in tests, not anywhere else.** +No mock resolvers, no fake DNS servers, no stubbed lookups. + +dnswatcher's entire purpose is correct behavior against the real DNS. +Tests exercise real iterative resolution against live nameservers by +design; a test suite that passes against a mock proves nothing about the +one thing this program exists to do. + +When live tests are flaky, that is a robustness problem, and it gets +fixed with robustness: retries with backoff, querying multiple +independent nameservers, longer timeouts — or explicit opt-in gating +decided by the project owner. Never with mocks. + +Contributions that introduce mocked, faked, or stubbed DNS will be +rejected. + +--- + ## Features ### DNS Domain Monitoring (Apex Domains)