docs: make the wiki the knowledge base and its upkeep a required step
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.
This commit is contained in:
2 files changed
+38
-3
No files matched your search
@@ -12,13 +12,41 @@ The main Claude session acts as the **task manager** and does not implement issu
|
||||
4. **PR comment handling by the agent**: After opening the PR, the development agent watches it for review comments. New comments are addressed automatically (code changes, reply on the thread), and addressed threads are marked as **resolved**.
|
||||
5. **Agent lifetime**: The development agent terminates itself once its PR has been merged (or closed).
|
||||
6. Only after the PR has been **merged by the user** may work on the next issue begin. The user merges; never merge yourself.
|
||||
7. **After the merge, verify the linked issue was closed** (auto-close via "Fixes #n"); close it manually if not. Gitea auto-closes on the same keywords, but only for an issue in the same repository — a migrated issue whose number changed is closed by hand.
|
||||
7. **Update the wiki — mandatory, in the same round of work as the change.** The wiki is this repo's knowledge base; a change that lands in `main` while the wiki still describes the old state has not been finished, it has been half-finished in a way nothing fails on. The development agent edits the affected pages **before** asking for the merge, so code and documentation are reviewed together. See "The wiki" below for what obliges an edit and what does not.
|
||||
8. **After the merge, verify the linked issue was closed** (auto-close via "Fixes #n"); close it manually if not. Gitea auto-closes on the same keywords, but only for an issue in the same repository — a migrated issue whose number changed is closed by hand. Check in the same step that the wiki edit really landed.
|
||||
|
||||
Additional rules for all commits, PRs, issues, and comments:
|
||||
|
||||
- Do **not** add a `Co-Authored-By` trailer and do **not** append "Generated with Claude Code" footers.
|
||||
- **Commits must be signed.** Verify the signature before opening the PR; if `op-ssh-sign` fails, stop and report rather than pushing unsigned work.
|
||||
|
||||
## The wiki
|
||||
|
||||
The knowledge base is the Gitea wiki at `https://git.jk-dev.de/jlab-cluster/helm-charts/wiki` — one page per chart (installation, required 1Password fields, every configurable value, the chart's traps) plus the long form of this workflow, the pipelines, the style guide and the incidents each rule was bought with. It is a **separate git repository**:
|
||||
|
||||
```bash
|
||||
git clone ssh://git@git.jk-dev.de:30022/jlab-cluster/helm-charts.wiki.git
|
||||
```
|
||||
|
||||
Flat layout, one Markdown file per page, page name = file name, links are relative page names without the extension (`[CI/CD](CI-CD)`). A new page must also be listed in `_Sidebar.md`, or it is reachable only by search.
|
||||
|
||||
**What obliges a wiki edit** (step 7 of the workflow above, same round of work, never a follow-up issue):
|
||||
|
||||
| Change | Page |
|
||||
| --- | --- |
|
||||
| a value added, removed, renamed, or its default changed | the chart's page — values table, and the operating notes if behaviour moved |
|
||||
| runtime behaviour changed (probes, hardening, restart semantics, a value becoming required) | the chart's page, plus `Lessons-Learned` if the reason could be repeated elsewhere |
|
||||
| a new chart | a new chart page, a row in `Charts`, an entry in `_Sidebar.md` |
|
||||
| a convention added or changed | `Chart-Style-Guide` (and README, which stays the code-side copy) |
|
||||
| pipeline, fixture or runner behaviour changed | `CI-CD` |
|
||||
| this issue workflow changed | `Workflow` — **and** this file, which is the binding copy |
|
||||
| a Renovate rule added or changed | `Renovate` |
|
||||
| something broke in a way a rule now prevents | `Lessons-Learned` |
|
||||
|
||||
**What does not oblige an edit:** a plain app-version bump. Renovate automerges those continuously and never touches the wiki, which is why chart pages quote versions as snapshots and name `Chart.yaml` as the source of truth. An app update that *does* change values or behaviour is not a plain bump, and the table applies.
|
||||
|
||||
Wiki commits follow the same rules as repo commits: no `Co-Authored-By`, no "Generated with Claude Code" footer.
|
||||
|
||||
## Which forge, and with which tool
|
||||
|
||||
Everything runs on the Gitea instance JLab-Git: issues, pull requests, CI and Renovate. github.com is a push mirror with Actions and Renovate **switched off**, and it lags until the mirror runs. README, "Where this repo lives", holds the measured differences between a Gitea runner and a GitHub one.
|
||||
@@ -35,6 +63,7 @@ Everything runs on the Gitea instance JLab-Git: issues, pull requests, CI and Re
|
||||
|
||||
- Changes to this issue workflow always go into this CLAUDE.md file.
|
||||
- General repository information (charts, CI pipelines, conventions, tooling) always lives in README.md. Any PR that changes repo-wide behavior must update README.md in the same PR.
|
||||
- **Operator-facing knowledge lives in the wiki**, not in README.md: how a chart is installed, what every value does, what its traps are. The division is `CLAUDE.md` binds the agent, `README.md` explains the repository to someone reading the code, the wiki explains the system to whoever runs it, and a chart's `NOTES.txt` explains one release. Where README and the wiki cover the same rule, both are updated in the same PR — see "The wiki" above.
|
||||
- Runtime verification of chart changes is done in a local, throwaway k3d cluster (k3d is installed on the maintainer's machine): stub CRD for `OnePasswordItem`, dummy secrets, throwaway infrastructure (postgres/redis) where needed.
|
||||
|
||||
## What this repo is
|
||||
|
||||
Reference in new issue
Block a user