OpenEnergyPlatform / OpenEnergyPlatform/oeplatform

Point the pinning tests at the documentation pages they describe

Open
#2,462 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation OEKG-API
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.