OpenEnergyPlatform / OpenEnergyPlatform/oeplatform
Point the pinning tests at the documentation pages they describe
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 65
- Forks
- 29
- Avg merge
- 15h 25m
- Merged PRs (30d)
- 32
Description
Parent
Spec: #2454 — Document and teach the OEKG REST API. Derived from WF-14 decision D9 and the third test in the spec's Testing Decisions.
What to build
A test that pins a documented behaviour names the page it describes, in its docstring. The pointer runs from the code to the doc, not the reverse: a citation in prose rots silently on a rename, while a pointer in the test fires at the moment someone changes the behaviour — the only moment the page is wrong.
This is not a new habit. The mechanism already exists in this repository in exactly one place, and that place is instructive: the one test that points at a document points at a research note in the maintainer's private vault, which an external contributor cannot read — and it was written by the very migration that left a developer-guide table stating two dropdown lists were hardcoded after both had been made dynamic. Wrong about two fields at once, found by a reader rather than by a check.
The rule: a test that pins a behaviour a documentation page describes names that page in its docstring — the page, not the vault note.
Acceptance criteria
- Each existing pinning test for the rules that have one names the client rules page in its docstring.
- The sector-dropdowns test's pointer is corrected from the vault note to the scenario-bundles architecture guide.
- A test in the schema test module collects every code→doc pointer and asserts that each named documentation page exists in the tree.
- That test asserts what is present; it does not require a pointer for a behaviour that has not been built.
- Changelog entry.
Carried obligation — not closable here
Two of the nine rules have no pinning test yet, because the behaviour is not built:
- rule 3 (delete-by-omission exists on
replace/and nowhere else) → its pointer lands with Replace the whole bundle in one call - rule 5 (the delete's two guards cover two different accidents) → its pointer lands with Delete a whole bundle, in two steps
Those two API slices should each gain the pointer as an acceptance criterion. Recorded here so the obligation is visible rather than assumed.
Blocked by
- #2457 — the generated API reference — the pointer-integrity test lives in the test module that ticket creates.
- #2460 — the client rules page — the pointers name that page.
- #2458 — the API write path section — the corrected sector-dropdowns pointer names the page that ticket edits.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the generated API reference and its test module from #2457, then inspect the existing pinning tests and the client rules and scenario-bundles documentation pages named in the acceptance criteria. Update each pointer, add the schema test that checks named pages exist, and add the changelog entry; completion is all listed criteria passing without requiring pointers for unbuilt behaviours.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, documentation, testing
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100