Epic: Expansion health (consistent version resolution, honest reporting, remediation)

Aperta
  • Qualcosa non va?
#2,942 4 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Ambito
backend-api-design

Direzione di ricerca

Start with the read-only analysis in OpenConceptLab/ocl_online#549 and the related issues listed here, especially #2236 and #2504. The epic spans version resolution, expansion rebuilding, API health reporting, TBv3, and remediation workflows; children are to be filed as work is scheduled. Pick up a scheduled child issue and use its scope to define what done looks like.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

component/api decision/human-review signal/has-dependencies signal/high-risk signal/large-scope signal/needs-access signal/needs-human stage/triaged type/feature

A collection expansion should resolve each repository consistently and say honestly what it holds. Today many stored expansions don't, and users can't see it. This epic covers how OCL judges an expansion's health, the code paths that produce unhealthy expansions, and how existing expansions get fixed. Evidence from a read-only analysis is in OpenConceptLab/ocl_online#549.

Definitions

  • Member: the concept version is held by the repository version its reference resolved to (healthy); or it's in HEAD (an unreleased version, not interim); or it's interim (a replaced version in neither a release nor HEAD; interim versions belong to authoring and shouldn't surface); or it's a mismatch (held by another version than the one resolved).
  • Expansion: healthy (narrow) when every unversioned reference to a repository resolves to one released version, every member is in its resolved version, and there are no interim members, no deprecated resource-version references, no duplicate or unresolved versions. HEAD-resolved (consistent, but at least one repository resolves to HEAD) is its own class. Anything else is unhealthy, with its reasons.

Behaviours that produce unhealthy expansions

  • A new collection version copies its references' stored results and its auto-expansion uses them without re-evaluating, while it records a freshly resolved version. A rebuild doesn't refresh references' stored results.
  • An unversioned filter reference returns concepts' HEAD rows whatever version the expansion is locked to.
  • The lock isn't applied on incremental adds to auto-expansions. It isn't reused when it's on HEAD or on a release since retired. Re-processing excludes and removing a reference both re-resolve.
  • A deprecated resource-version reference resolves to the latest release rather than the newest version that holds the pinned row, so a rebuild can silently drop it (OpenConceptLab/ocl_issues#2504).
  • Each reference's resolved repository versions are re-resolved at request time, so what the API and TBv3 show can disagree with the expansion's own lock. Some expansions list a version as both explicit and evaluated.
  • Expansions built before version locking record every version as explicit (#2236's backfill never ran).

Work (children to be filed as they're scheduled)

  • Stop silent content loss on rebuild for resource-version references, then resolve them to the newest version holding the pinned row
  • Re-evaluate (or refresh stored results) under the lock when creating a collection version and when rebuilding
  • Unversioned filter references resolve within the locked version
  • Apply and reuse the lock on every path (incremental add, exclude re-processing, removal, HEAD locks)
  • Show each expansion's recorded versions once, without re-resolving
  • Health classification (members and expansion, with reasons) in the API
  • Health badge and reasons in TBv3
  • Back end: rebuild every expansion's explicit/evaluated version lists from what it holds (metadata only, no membership change)
  • Workflow: create a fixed version of an unhealthy released collection version, with a diff preview
  • Workflow: convert resource-version references, showing what each conversion keeps
  • Workflow: move a HEAD-resolved expansion to a release once one exists
  • Analyse mappings the same way

Generated expansions stay frozen. Back-end fixes are limited to changes that leave members as they are; anything that changes a released version's members is the owner's choice, through a workflow.

Related: OpenConceptLab/ocl_issues#2236, #2312, #2438, #2504, #2349, #2941; OpenConceptLab/ocl_online#549.

Lingua principale
Nessun dato sulla lingua
Stelle
4
Fork
2
Merge medio
2h 12m
PR unite (30g)
1

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di OpenConceptLab/ocl_issues

Tutte le issue di OpenConceptLab/ocl_issues

Issue simili

Altre issue su Backend & API Design

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.