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>
2.6 KiB
2.6 KiB
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.jsrenames a field, nothing forces the wiki to follow. User preference is "single package" — clone once, edit together, review together.
Options
- 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.
- Move docs + diagrams into
pumpingStation.git/wiki/(selected)
- Benefits: Single package —
git clone pumpingStationgets 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.gitto a pointer at the new location.
- 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.mdacts as the index instead.
Consequences
- Compatibility impact: Anyone bookmarking
RnD/pumpingStation/wiki/Functional-Descriptionlands 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.gitHome 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/*.mdback into.wiki.git, update.wiki.gitHome to point at itself. - Migration/deprecation plan: The pointer page stays indefinitely.