docs(readme): add comprehensive README #517

Merged

fuzzy merged 1 commit from docs/readme into main

2026-08-04 02:22:36 +00:00

automation commented

2026-08-04 02:13:11 +00:00

Owner

What

Add a comprehensive README.md documenting thwap-pagesd end to end:

Overview (#101) — what the daemon does, its lifecycle (register, publish, preview, rollback), an architecture diagram, and a component breakdown.
Setup (#102) — prerequisites, the full configuration reference (keys, defaults, THWAP_PAGESD_ env vars), an example thwap-pagesd.yaml, build/run instructions, and container usage.
API reference (#103) — every endpoint (/healthz, /readyz, /metrics, /api/v1/sites*, /webhook) with request/response shapes and status codes, plus the Site and Deployment models.

Why

Phase 8 task #104 — first-time documentation so operators can deploy and integrate the daemon.

Testing

go build ./...
go vet ./...
go test -race ./...
gofmt -l ./cmd ./internal ./pkg clean
golangci-lint run — 0 issues
pre-commit hooks all pass

Breaking Changes

None.

Notes

Issues #101, #102, #103, #104 closed via the Forgejo API as part of this task per the workflow.

Closes #101
Closes #102
Closes #103
Closes #104

## What Add a comprehensive `README.md` documenting thwap-pagesd end to end: - **Overview (#101)** — what the daemon does, its lifecycle (register, publish, preview, rollback), an architecture diagram, and a component breakdown. - **Setup (#102)** — prerequisites, the full configuration reference (keys, defaults, `THWAP_PAGESD_` env vars), an example `thwap-pagesd.yaml`, build/run instructions, and container usage. - **API reference (#103)** — every endpoint (`/healthz`, `/readyz`, `/metrics`, `/api/v1/sites*`, `/webhook`) with request/response shapes and status codes, plus the `Site` and `Deployment` models. ## Why Phase 8 task #104 — first-time documentation so operators can deploy and integrate the daemon. ## Testing - [x] `go build ./...` - [x] `go vet ./...` - [x] `go test -race ./...` - [x] `gofmt -l ./cmd ./internal ./pkg` clean - [x] `golangci-lint run` — 0 issues - [x] pre-commit hooks all pass ## Breaking Changes None. ## Notes - Issues #101, #102, #103, #104 closed via the Forgejo API as part of this task per the workflow. Closes #101 Closes #102 Closes #103 Closes #104

automation added 1 commit

2026-08-04 02:13:11 +00:00

docs(readme): add comprehensive README

Test and Release / lint (pull_request) Successful in 26s

Details

Test and Release / test (pull_request) Successful in 26s

Details

b11f97d2b7

Document thwap-pagesd end to end:

- Overview: what the daemon does and how it works with Forgejo and
  Kubernetes, including an architecture diagram
- Setup: prerequisites, configuration reference (all keys, defaults,
  and THWAP_PAGESD_ environment variables), an example YAML config,
  build/run instructions, and container usage
- API reference: every endpoint (health, metrics, sites, webhook)
  with request/response shapes and status codes, plus the Site and
  Deployment models

Mark task done in ROADMAP.md.

closes #101
closes #102
closes #103
closes #104

automation added the

Kind/Documentation

label

2026-08-04 02:13:21 +00:00

the.auditor approved these changes

2026-08-04 02:16:27 +00:00

the.auditor left a comment

Review Summary

Verified locally on the PR head (b11f97d): build/vet/full test suite pass (docs-only, no code impact).

The README is thorough and — with one exception — accurate against the implementation. I cross-checked the config reference, env-var mapping, endpoints, status codes, models, and webhook behavior against the code: all match, including the correct <public_url>/webhook target derivation and the tag-deletion→rollback / test/*→preview routing. The architecture diagram and component table are a good orientation aid.

No blocking issues.

Non-blocking observations:

kubernetes.kubeconfig is documented as "Explicit kubeconfig path (default: in-cluster or ~/.kube/config)", but the key is never consumed — kubernetes.NewClient() takes no args and always uses in-cluster config with default loading rules (verified via rg; the field has been dead since #129). Setting THWAP_PAGESD_KUBERNETES_KUBECONFIG has no effect. Suggest either wiring the key into NewClient or marking it "not yet wired" in the README so operators aren't misled.
The webhook behavior table is a slight simplification — non-preview branch pushes (e.g. main) also trigger a production publish, and non-v* tag pushes do too (the reselect just ignores them). Fine for an overview, worth a footnote if the README grows.
The container section doesn't mention that the image needs kubeconfig/Forgejo reachability at startup (per the pre-existing eager forgejo.NewClient version check) — worth one line in the container usage.

Approving.

## Review Summary Verified locally on the PR head (`b11f97d`): build/vet/full test suite pass (docs-only, no code impact). The README is thorough and — with one exception — accurate against the implementation. I cross-checked the config reference, env-var mapping, endpoints, status codes, models, and webhook behavior against the code: all match, including the correct `<public_url>/webhook` target derivation and the tag-deletion→rollback / `test/*`→preview routing. The architecture diagram and component table are a good orientation aid. **No blocking issues.** Non-blocking observations: 1. `kubernetes.kubeconfig` is documented as "Explicit kubeconfig path (default: in-cluster or `~/.kube/config`)", but the key is never consumed — `kubernetes.NewClient()` takes no args and always uses in-cluster config with default loading rules (verified via `rg`; the field has been dead since #129). Setting `THWAP_PAGESD_KUBERNETES_KUBECONFIG` has no effect. Suggest either wiring the key into `NewClient` or marking it "not yet wired" in the README so operators aren't misled. 2. The webhook behavior table is a slight simplification — non-preview branch pushes (e.g. `main`) also trigger a production publish, and non-`v*` tag pushes do too (the reselect just ignores them). Fine for an overview, worth a footnote if the README grows. 3. The container section doesn't mention that the image needs kubeconfig/Forgejo reachability at startup (per the pre-existing eager `forgejo.NewClient` version check) — worth one line in the container usage. Approving.

fuzzy merged commit b11f97d2b7 into main

2026-08-04 02:22:36 +00:00

fuzzy deleted branch docs/readme

2026-08-04 02:22:36 +00:00