Versionering för openEHR-templates
Innehållsförteckning
Versionshistorik
Version | Datum | Beskrivning | Ansvarig |
1.0 | 2024-05-27 | Publicerat första version. | openEHR Sverige |
2.0 | 2025-01-03 | Justering av text kring hur template-namn och template_ID sätts, samt lagt till stycke 2.2.3. | Oscar Karlsson |
1 Syfte
Syftet med detta dokument är att dokumentera hur vi i openEHR Sverige vill jobba med versionering för openEHR-templates, för att:
underlätta och effektivisera arbetet med templates
ha ett underlag att ta vidare till olika forum för att jobba för gemensamma överenskommelser kring detta.
2 Flöde för utveckling och versionering av en template
2.1 Hög-nivå-översikt
Använd semantiskt korrekt versionering
Generellt så ska vi sträva efter att följa den semantiska versionering som beskrivs på Semantic Versioning 2.0.0 . Detta gäller dock framför allt publicerade versioner. T.ex. så ska man stega major-versionen om man gör icke bakåt-kompatibla ändringar i en publicerad version.
För preliminära versioner (alpha-versioner) kan man dock göra även icke-bakåt-kompatibla ändringar under utvecklings-fasen, dvs. mellan olika alpha-versioner (z.y.z-alpha.1 -> x.y.x-alpha.2 etc.), vilket också framgår/antyds på länken ovan.
Använd flödet Alpha-version → RC-version → Publicerad version → Uppdaterad version, iterativt för varje ny template som ska utvecklas.
2.2 Detaljerad beskrivning – flöde för versioner (Alpha-version → RC-version → Publicerad version → Uppdaterad version)
2.2.1 Alpha-version: preliminär (pre-release) template-version
En ny template börjar som en preliminär template-version och namnges då med alpha-suffix, dvs. t.ex. 1.0.0-alpha för en första preliminär version som senare ska publiceras som version 1.0.0. Templaten stegas inom alpha-versionen med ett nummer-suffix (dvs. till 1.0.0-alpha.2 etc.) tills att man har en version som är tillräckligt stabil för att kunna vara en release candidate (se nedan). Ändringar som leder till en stegning inom alpha-versionen kan vara allt från enkla rättningar av stavfel till icke bakåt-kompatibla ändringar.
template-namn (dvs. översta rotnoden) ska spegla templatens innehåll och vara förståeligt för kliniker. Mellanslag och ÅÄÖ kan användas. Denna översätts till alla, för templaten, relevanta språk. T.ex. ”Läkemedelsordination” och ”Medication order”.
template_id ska anges på engelska och sätts till <use case + template-namn>.v<major version>, dvs. t.ex. ChemotherapyMedicationOrder.v1 (finns inget lokaliseringsstöd i dagsläget).
sem_ver sätts till <major version>.<minor version>.<patch version>-alpha.<alpha version>, dvs. t.ex. 1.0.0-alpha.1 som stegas till 1.0.0-alpha.2, 1.0.0-alpha.3 osv (man kan behöva justera föreslagen sem_ver i dialogen i Archetype designer)
build_uid genereras om vid varje commit, dvs. varje gång man trycker på Save (behöver göras aktivt i dialogen i Archetype designer), eller åtminstone vid varje ny sem_ver
Det går även bra att börja på major-version 0, dvs. på version 0.x.y, så länge man endast arbetar i Archetype Designer. Dock bör man sätta en preliminär version som matchar den version som senare ska release:as (t.ex. 1.0.0-alpha.1), innan man börjar använda template-en bredare, i t.ex. formulär-verktyg. Detta för att smidigt kunna synka in uppdateringar i verktygen utan att behöva bygga om t.ex. formulär
2.2.2 RC-version: Release Candidate av template-version
När man har en release candidate, dvs. man tror att man har en version som är tillräckligt stabil för att kunna börja användas kliniskt så skapar man en rc-version, t.ex. 1.0.0-rc.1. Sedan testar man denna i testmiljö och utvärderar, och justerar vid behov till ytterligare rc-versioner.
template_id ändras inte utan är fortfarande <use case + template-namn>.v<major version>, dvs. t.ex. ChemotherapyMedicationOrder.v1
sem_ver sätts till <major version>.<minor version>.<patch version>-rc.<rc version>, dvs. t.ex. 1.0.0-rc.1 som stegas till 1.0.0-rc.2, 1.0.0-rc.3 osv
build_ui genereras om vid varje commit, dvs. varje gång man trycker på Save (behöver göras aktivt i dialogen i Archetype designer), eller åtminstone vid varje ny sem_ver
2.2.3 Publicerad version
När man har en version som man anser vara färdig så skapar man en version som kan publiceras, t.ex. 1.0.0.
template_id ändras inte utan är fortfarande <use case + template-namn>.v<major version>, dvs. t.ex. ChemotherapyMedicationOrder.v1
sem_ver sätts till <major version>.<minor version>.<patch version>, dvs. t.ex. 1.0.0
build_ui genereras om vid varje commit, dvs. varje gång man trycker på Save (behöver göras aktivt i dialogen i Archetype designer), eller åtminstone vid varje ny sem_ver
2.2.4 Uppdaterad version
När templaten har publicerats i en första version kan den behöva uppdateras. Avser man t.ex. att skapa en version 2.0.0 så skapas det en alpha-, rc-, resp. publicerad version i enlighet med steg 1-3, dvs. först skapas en exempelvis en 2.0.0-alpha.1 (som stegas enligt behov), sedan en 2.0.0-rc.1 (som stegas enligt behov) och slutligen en 2.0.0 publicerad version. Avser man t.ex. att skapa en version 1.1.0 så skapas det på liknande sätt en alpha-, rc-, resp. publicerad version i enlighet med steg 1-3, dvs. först skapas en exempelvis en 1.1.0-alpha.1 (som stegas enligt behov), sedan en 1.1.0-rc.1 (som stegas enligt behov) och slutligen en 1.1.0 publicerad version.
2.2.3 Språkskillnader i Path-namn och AQL-frågor
Patherna som visas i flat-format inleds med template-namn på det primära exportspråket. Då vi i svensk kontext i de allra flesta fall kommer att exportera med primärspråk svenska kommer template_id att skilja sig från patherna. Även namnet på respektive nod i compositionen kommer att vara på det primära exportspråket, vilket betyder att AQL-frågor måste matchas mot detta.
2.3 Lathund – att tänka på när du sparar i Archetype Designer
Några saker som är bra att tänka på när man sparar en template från Archetype Designer:
Generera om build_uid:
när du klickar på ”Save” i Archetype Designer får du upp nedan dialog. Ta för vana att alltid klicka på knappen bredvid Build Uid, så att det genereras ett nytt build uid:
Kontrollera vilken semantisk version som verktyget föreslår, och korrigera vid behov. För alpha-versioner måste du alltid korrigera den föreslagna versionen, så att du endast stegar den sista siffran (dvs. siffran efter ”alpha”):
Skriv gärna en rad om vad du ändrat, och gärna på engelska:
