From 8d090864af6fe825df5b1adb70cf097818121336 Mon Sep 17 00:00:00 2001 From: Konrad Neitzel Date: Wed, 30 Sep 2026 17:29:11 +0200 Subject: [PATCH] Record the setup-change closeout and the module glossary. The change notes finish the documentation pass, and CONTEXT.md points at the project specification. --- .../project-specification.mdc => CONTEXT.md | 20 ++-- docs/changes/00001-setup-project/changes.md | 92 +++++++++++++++++++ .../00001-setup-project/verification.md | 65 +++++++++++++ 3 files changed, 167 insertions(+), 10 deletions(-) rename .cursor/rules/project-specification.mdc => CONTEXT.md (61%) create mode 100644 docs/changes/00001-setup-project/changes.md create mode 100644 docs/changes/00001-setup-project/verification.md diff --git a/.cursor/rules/project-specification.mdc b/CONTEXT.md similarity index 61% rename from .cursor/rules/project-specification.mdc rename to CONTEXT.md index 8a38314..a5d4373 100644 --- a/.cursor/rules/project-specification.mdc +++ b/CONTEXT.md @@ -1,11 +1,8 @@ ---- -description: go-dns — Go library for dynamic DNS updates (RFC 2136 / nsupdate-style) -alwaysApply: true ---- +# go-dns -# go-dns — Project Rules +Go library for dynamic DNS updates (RFC 2136 / nsupdate-style). -Follow `docs/project-specification.md` for design and implementation. +**Canonical spec:** [docs/project-specification.md](./docs/project-specification.md) — follow it for design and implementation. ## Stack @@ -14,7 +11,7 @@ Follow `docs/project-specification.md` for design and implementation. - **Package:** `godns` (module root) - **Type:** Importable Go library (not a standalone service) -## Design +## Design (summary) - Target **BIND** and RFC 2136–compatible authoritative nameservers - **Dynamic update** (RFC 2136) and **full zone transfer** (AXFR) over DNS @@ -22,12 +19,15 @@ Follow `docs/project-specification.md` for design and implementation. - Typed **RR builders** per record type (not generic rdata strings) - Domain names: **ASCII only** in v1 - UPDATE: **automatic TCP fallback** on UDP truncation -- Integration tests: **BIND testcontainer** (`go test -tags=integration ./...`) -- **`docs/bind-tsig-configuration.md`** — BIND `allow-update` / `allow-transfer` guide - Typed **zone data structures** (`Record`, `Zone`, etc.) for transfer/update results -- Project `.cursor` overrides workspace rules for this module +- BIND guide: [docs/bind-tsig-configuration.md](./docs/bind-tsig-configuration.md) +- Project docs override workspace defaults for this module ## Tests - Unit: `go test ./...` - Integration: `go test -tags=integration ./...` — **BIND testcontainer** (Docker required) + +## Work tracking + +Local markdown issues: [../.scratch/](../.scratch/) — see [docs/agents/issue-tracker.md](../docs/agents/issue-tracker.md). diff --git a/docs/changes/00001-setup-project/changes.md b/docs/changes/00001-setup-project/changes.md new file mode 100644 index 0000000..59c9bb6 --- /dev/null +++ b/docs/changes/00001-setup-project/changes.md @@ -0,0 +1,92 @@ +# Changes: Initial project setup and DNS operation catalog + +## Summary + +Change **00001-setup-project** bootstrapped the **go-dns** project: a new Go module in the workspace, Gitea repository on branch `feature/C-00001-setup-project`, full DNS operation catalog in `spec.md`, product documentation, Cursor project rule, product backlog, and **`docs/bind-tsig-configuration.md`** (BIND TSIG setup for dynamic updates and AXFR). No Go library code, TSIG/UPDATE/AXFR implementation, or integration tests were added — those are deferred to future changes. Verification passed with one accepted gap (`go work sync` blocked by a pre-existing `log-analyzer` workspace issue). + +## Change folder + +`go-dns/docs/changes/00001-setup-project/` + +| Artifact | Status | +|----------|--------| +| `spec.md` | Baseline commit | +| `plan.md` | Baseline commit | +| `impl-decisions.md` | Implementation commit | +| `verification.md` | Verify phase (local; commit with this document) | +| `changes.md` | This document (document phase) | + +## Files changed + +### Specify phase (baseline commit `47f1744`) + +| Path | Change | +|------|--------| +| `go.mod` | added | +| `.gitignore` | added | +| `.cursor/rules/project-specification.mdc` | added | +| `docs/project-specification.md` | added | +| `docs/backlog.md` | added | +| `README.md` | added | +| `docs/changes/00001-setup-project/spec.md` | added | +| `docs/changes/00001-setup-project/plan.md` | added | + +### Implement phase (commit `eff7637`) + +| Path | Change | +|------|--------| +| `docs/bind-tsig-configuration.md` | added | +| `docs/project-specification.md` | modified — live BIND guide links | +| `README.md` | modified — BIND guide link | +| `.gitignore` | modified — `.env` / `.env.*` | +| `.cursor/rules/project-specification.mdc` | modified — guide path wording | +| `docs/changes/00001-setup-project/impl-decisions.md` | added | + +### Verify and document phases (local, not yet committed) + +| Path | Change | +|------|--------| +| `docs/changes/00001-setup-project/verification.md` | added | +| `docs/changes/00001-setup-project/changes.md` | added | + +### Workspace (outside `go-dns` git repo) + +| Path | Change | +|------|--------| +| `go.work` (workspace root) | `./go-dns` listed under `use (...)` — not in project git history | + +### Git history + +| Commit | Contents | +|--------|----------| +| `47f1744` `chore: baseline before change C-00001-setup-project` | Specify-phase scaffolding and change docs | +| `eff7637` `docs: add BIND TSIG guide and align project documentation` | BIND guide, doc alignment, `impl-decisions.md` | + +## Deviations from plan or spec + +| Deviation | Notes | +|-----------|-------| +| **`go work sync`** | Fails from workspace root because `log-analyzer/` is in `go.work` without `go.mod`. Not caused by this change. See [verification.md](verification.md) accepted gap AC-1. | +| **No Go source** | Plan and spec explicitly exclude library implementation; no `package godns` files yet. | +| **Otherwise** | None — BIND guide matches spec section 9; backlog preserved; no scope creep. | + +## Verification reference + +**Result:** Pass with one accepted gap ([verification.md](verification.md)). + +| AC | Result | +|----|--------| +| AC-1 | Pass (accepted gap) — `go work sync` fails on `log-analyzer` | +| AC-2 – AC-10 | Pass | + +## Follow-ups + +| Item | Suggested action | +|------|------------------| +| Commit `verification.md` and `changes.md`; push branch | User / git | +| Fix workspace `go.work` / `log-analyzer` | Separate workspace change | +| Merge `feature/C-00001-setup-project` to `main` on Gitea | After review | +| Implement `package godns` (RFC 2136 UPDATE, AXFR, TSIG) | Next change per spec | +| Typed RR builders, zone data types in Go | With or after protocol change | +| BIND testcontainer integration tests | After minimal library surface exists | +| IXFR support | Backlog P2 — [backlog.md](../../backlog.md) | diff --git a/docs/changes/00001-setup-project/verification.md b/docs/changes/00001-setup-project/verification.md new file mode 100644 index 0000000..4d0c041 --- /dev/null +++ b/docs/changes/00001-setup-project/verification.md @@ -0,0 +1,65 @@ +# Verification: Initial project setup and DNS operation catalog + +## Environment + +| Item | Value | +|------|-------| +| OS | Darwin 25.5.0 (arm64) | +| Go | go1.26.4 | +| Project | `go-dns/` | +| Branch | `feature/C-00001-setup-project` | +| Docker | Not required for this change | +| Integration tests | N/A (no Go source; BIND testcontainer deferred) | + +## Commands run + +| Command | Directory | Exit code | Notes | +|---------|-----------|-----------|-------| +| `go version` | — | 0 | go1.26.4 darwin/arm64 | +| `grep -q go-dns go.work` | `/Users/konrad/Projects/go` | 0 | Module listed in workspace | +| `go work sync` | `/Users/konrad/Projects/go` | 1 | Fails: `log-analyzer/go.mod` missing (pre-existing workspace issue) | +| `grep module/go lines go.mod` | `go-dns/` | 0 | Correct module path and Go version | +| `test -f .cursor/rules/project-specification.mdc` + greps | `go-dns/` | 0 | AC-3 | +| `rg` content check | `go-dns/docs/project-specification.md` | 0 | AC-4 | +| `rg` content check | `go-dns/README.md` | 0 | AC-5 | +| `rg -n '^### [0-9]+\.' spec.md` | change folder | 0 | Sections 1–10 present (AC-6) | +| BIND guide content check | `go-dns/docs/bind-tsig-configuration.md` | 0 | AC-7 | +| `rg IXFR backlog.md` | `go-dns/docs/backlog.md` | 0 | AC-8 | +| Change folder artifacts | `00001-setup-project/` | 0 | spec, plan, impl-decisions present (AC-9) | +| Resolved decisions grep | `spec.md` | 0 | AC-10 | +| `go test ./...` | `go-dns/` (GOWORK=off) | 1 | No packages to test — expected; no Go source in this change | +| `git log -2 --oneline` | `go-dns/` | 0 | Baseline + implementation commits on feature branch | + +## Results summary + +**Overall: pass** (one accepted workspace gap for AC-1). + +Change **00001-setup-project** delivers documentation and scaffolding only: git repository on Gitea, project docs, operation catalog in `spec.md`, and **`docs/bind-tsig-configuration.md`**. No Go library code, unit tests beyond empty module, or integration tests — all consistent with plan and spec. + +Implementation commits: `47f1744` (baseline), `eff7637` (BIND guide and doc alignment). + +## Acceptance criteria checklist + +| # | Criterion | Result | Evidence | +|---|-----------|--------|----------| +| AC-1 | `go-dns` in `go.work`; `go work sync` succeeds | **pass (accepted gap)** | `grep -q go-dns go.work` → exit 0. `go work sync` → exit 1: `cannot load module log-analyzer ... go.mod: no such file or directory`. Not caused by this change; `go-dns/go.mod` is valid. | +| AC-2 | `go.mod` module path and Go 1.26.4 | **pass** | `module gitea.neitzel.de/konrad/go-dns`, `go 1.26.4` | +| AC-3 | `.cursor/rules/project-specification.mdc` | **pass** | File exists; `alwaysApply: true`; references `docs/project-specification.md` | +| AC-4 | `docs/project-specification.md` complete | **pass** | Matches for module path, `godns`, BIND, RFC 2136, AXFR, TSIG, zone model types, `bind-tsig-configuration` | +| AC-5 | `README.md` in English with required links | **pass** | Updates, AXFR, module path, `godns`, spec link | +| AC-6 | `spec.md` sections 1–10 | **pass** | `rg -n '^### [0-9]+\.'` shows sections 1–10; AXFR only (IXFR in non-goals/backlog) | +| AC-7 | BIND guide requirements | **pass** | `docs/bind-tsig-configuration.md` exists; contains `allow-update`, `allow-transfer`, `tsig-keygen`, `named-checkconf`, `rndc reload`, `update-policy`, `hmac-sha256`, security notes, full `key` + `zone` example | +| AC-8 | `docs/backlog.md` IXFR entry | **pass** | P2 IXFR row present | +| AC-9 | Change folder layout | **pass** | `spec.md`, `plan.md`, `impl-decisions.md` present; `verification.md` added in verify phase | +| AC-10 | Resolved decisions in spec | **pass** | Table covers `godns`, typed builders, AXFR-only, BIND testcontainer, TCP fallback, ASCII-only, git init in implementation | + +## Accepted gaps + +| Criterion | Gap | Rationale | +|-----------|-----|-----------| +| AC-1 (`go work sync`) | Workspace sync fails due to missing `log-analyzer/go.mod` | Pre-existing workspace configuration issue outside `go-dns` scope. `go-dns` module and `go.work` entry are correct. Fix belongs to workspace or `log-analyzer` maintenance, not this change. | + +## Follow-up + +- Run **`/document-agent`** to write `changes.md`. +- Next change: implement `package godns` (RFC 2136 UPDATE, AXFR, TSIG) per spec and backlog.