docs: make the wiki the knowledge base and its upkeep a required step #27

2026-09-18T10:55:12+02:00

jlab-bot commented

2026-09-18 10:55:12 +02:00

The wiki was empty. It now carries the repository knowledge that until today lived only in the templates, in NOTES.txt and in the README.

Wiki (36 pages, pushed to helm-charts.wiki):

One page per chart, all to the same structure: at a glance, prerequisites, installation with a minimal values file, the required 1Password fields, the complete values reference (every key from values.yaml and values.schema.json, required values with their exact condition), operating notes, upgrades and backup, CI fixtures.
Eleven topic pages: workflow, forge and tooling, CI/CD, versioning, Renovate, chart style guide, creating a new chart, local development, lessons learned, chart index, home.
Chart pages quote versions as snapshots and name Chart.yaml as authoritative, because Renovate moves app versions continuously and never edits the wiki.

This PR:

README.md points at the wiki up front, at the per-chart pages from the chart table, and at the matching pages from "Creating a new chart" and "Chart style guidelines". It keeps its own role: the overview for someone reading the code, while anything an operator needs lives in the wiki.
CLAUDE.md gains the wiki edit as step 5 of the mandatory workflow — before the merge is requested, so code and documentation are reviewed together — plus a "The wiki" section with a table of what obliges an edit. A plain app-version bump deliberately does not: Renovate automerges those and never touches the wiki, and a rule that fires on every automerged PR would rot within a week.
Corrects the patchmon row: the 2.x server serves frontend and /api/* from one process, so the chart renders one Deployment plus an optional guacd sidecar, not two Deployments. Verified against patchmon/templates/.

Reading the charts for the values tables turned up a list of contradictions and dead values (stale no dependencies comments in every _helpers.tpl, patchmon values comments that contradict its own required(), five homeassistant values no template renders, the teamspeak licence expiring 2026-10-01). Those are not touched here — they belong in their own issues.

The wiki was empty. It now carries the repository knowledge that until today lived only in the templates, in `NOTES.txt` and in the README. **Wiki** (36 pages, pushed to `helm-charts.wiki`): - **One page per chart**, all to the same structure: at a glance, prerequisites, installation with a minimal values file, the required 1Password fields, the **complete** values reference (every key from `values.yaml` and `values.schema.json`, required values with their exact condition), operating notes, upgrades and backup, CI fixtures. - **Eleven topic pages**: workflow, forge and tooling, CI/CD, versioning, Renovate, chart style guide, creating a new chart, local development, lessons learned, chart index, home. - Chart pages quote versions as snapshots and name `Chart.yaml` as authoritative, because Renovate moves app versions continuously and never edits the wiki. **This PR:** - `README.md` points at the wiki up front, at the per-chart pages from the chart table, and at the matching pages from "Creating a new chart" and "Chart style guidelines". It keeps its own role: the overview for someone reading the code, while anything an operator needs lives in the wiki. - `CLAUDE.md` gains the wiki edit as **step 5** of the mandatory workflow — before the merge is requested, so code and documentation are reviewed together — plus a "The wiki" section with a table of what obliges an edit. A plain app-version bump deliberately does not: Renovate automerges those and never touches the wiki, and a rule that fires on every automerged PR would rot within a week. - Corrects the `patchmon` row: the 2.x server serves frontend and `/api/*` from one process, so the chart renders one Deployment plus an optional guacd sidecar, not two Deployments. Verified against `patchmon/templates/`. Reading the charts for the values tables turned up a list of contradictions and dead values (stale `no dependencies` comments in every `_helpers.tpl`, `patchmon` values comments that contradict its own `required()`, five `homeassistant` values no template renders, the teamspeak licence expiring 2026-10-01). Those are not touched here — they belong in their own issues.

jlab-bot added 2 commits 2026-09-18 10:55:13 +02:00

docs: make the wiki the knowledge base and its upkeep a required step 03bb454eb7

The wiki now carries one page per chart (prerequisites, installation, the
required 1Password fields, the complete values reference and the chart's
traps) plus the workflow, the pipelines, versioning, Renovate, the style
guide and the incidents behind each rule.

README points at it and keeps its own role: the overview for someone reading
the code, while anything an operator needs lives in the wiki. CLAUDE.md gains
the wiki edit as step 7 of the mandatory workflow, with a table of what
obliges an edit - and the one thing that does not, a plain app-version bump,
since Renovate automerges those and never touches the wiki.

Also corrects the patchmon row: the 2.x server serves frontend and /api/* from
one process, so the chart renders one Deployment plus an optional guacd
sidecar, not two Deployments.

docs: order the wiki step before the merge, not after it

Validate Helm Charts / Detect changed charts (pull_request) Successful in 3s

Details

Validate Helm Charts / Build ${{ fromJSON(needs.detect-changed-charts.outputs.charts) }} (pull_request) Skipped

Details

Validate Helm Charts / Trivy config ${{ fromJSON(needs.detect-changed-charts.outputs.scan-charts) }} (pull_request) Skipped

Details

Validate Helm Charts / Install-test ${{ fromJSON(needs.detect-changed-charts.outputs.install-charts) }} (pull_request) Skipped

Details

Validate Helm Charts / Resource quantities (pull_request) Successful in 8s

Details

feb70cf1e4