79afe11da8
Some checks failed
CI / lint-and-test (push) Has been cancelled
Four decisions recorded under .agents/decisions/ per project convention (DECISION-YYYYMMDD-slug.md) to close the loop on today's pumpingStation refactor + eval + docs work: - wiki-in-code-repo — why docs+diagrams+code now live in one package - 5-threshold-naming — old/new field mapping + breaking-change rationale - mode-tier-template — Tier 1/2/3 classification for mode pages - eval-harness — why eval/ exists alongside test/ Also bumps nodes/pumpingStation to 66fd3fe (eval harness + Tier 2/3 template pages). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
42 lines
2.6 KiB
Markdown
42 lines
2.6 KiB
Markdown
# DECISION-20260422-pumpingstation-wiki-in-code-repo
|
|
|
|
## Context
|
|
- Task/request: Document pumpingStation functional behaviour (basin model, control modes, safety). Initial draft went into the Gitea wiki repo (`pumpingStation.wiki.git`).
|
|
- Impacted files/contracts: location of all pumpingStation documentation; how docs, diagrams, and code stay in sync; wiki UI vs repo browsing UX.
|
|
- Why a decision is required now: Wiki repo + code repo diverge silently. When `specificClass.js` renames a field, nothing forces the wiki to follow. User preference is "single package" — clone once, edit together, review together.
|
|
|
|
## Options
|
|
1. Keep docs in `pumpingStation.wiki.git` (Gitea's native wiki)
|
|
- Benefits: Gitea wiki UI (Pages dropdown, `?edit=1`, dedicated URL).
|
|
- Risks: Two separate repos; code and doc drift silently.
|
|
- Rollout notes: Status quo as of 2026-04-22.
|
|
|
|
2. Move docs + diagrams into `pumpingStation.git/wiki/` (selected)
|
|
- Benefits: Single package — `git clone pumpingStation` gets code + docs + diagrams. Atomic commits can change code + doc + diagram together. Diagrams version-lock with the class they describe.
|
|
- Risks: Lose the Gitea wiki Pages dropdown. Browsing is via the repo tree.
|
|
- Rollout notes: Shrink the `.wiki.git` to a pointer at the new location.
|
|
|
|
3. Hybrid — diagrams only in code repo, Markdown pages in `.wiki.git`
|
|
- Benefits: Keep Gitea wiki UI.
|
|
- Risks: Image URLs break silently on rename; still two repos to sync.
|
|
- Rollout notes: Not pursued.
|
|
|
|
## Decision
|
|
- Selected option: Option 2 — everything under `pumpingStation/wiki/`.
|
|
- Decision owner: User (r.de.ren@brabantsedelta.nl)
|
|
- Date: 2026-04-22
|
|
- Rationale: Single package > Gitea wiki UI convenience. Review-as-one-PR pattern is worth more than the Pages dropdown. `wiki/README.md` acts as the index instead.
|
|
|
|
## Consequences
|
|
- Compatibility impact: Anyone bookmarking `RnD/pumpingStation/wiki/Functional-Description` lands on a one-line pointer. Breaking but low-impact.
|
|
- Safety/security impact: None.
|
|
- Data/operations impact: Future contributors must know to edit `wiki/` inside the code repo, not the wiki repo. Pointer page on the Gitea wiki explains.
|
|
|
|
## Implementation Notes
|
|
- Required code/doc updates: `pumpingStation/wiki/{functional-description.md, README.md, modes/, diagrams/}` populated; `.wiki.git` Home shrunk.
|
|
- Validation evidence required: Raw Gitea URLs resolve; `https://gitea.wbd-rd.nl/RnD/pumpingStation/src/branch/main/wiki/` browses cleanly.
|
|
|
|
## Rollback / Migration
|
|
- Rollback strategy: Reverse — copy `pumpingStation/wiki/*.md` back into `.wiki.git`, update `.wiki.git` Home to point at itself.
|
|
- Migration/deprecation plan: The pointer page stays indefinitely.
|