# 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.