MO-17, Aanpassing stelsel versienummer op basis van SemVer
- Martin Wilmink
- Marlotte Pannekoek
Uitgangspunten:
Het MedMij afspraken stelsel volgt een groeipad waarbij regelmatig aanpassingen, toevoegingen plaatsvinden. De aanpassingen volgen het release management proces. Een release wordt samengesteld op basis van opgeleverde change requests.
Om deze wijzigingen goed in de tijd te kunnen volgen en zeker te zijn dat we de continuïteit van de MedMij stelsel gegevensuitwisseling waarborgen is een consequente versiebeheer noodzakelijk. Waarbij de versie nummering ook duiding geeft over de impact van de publicatie tov de voorgaande versie.
De uitgangspunten voor de gepresenteerde oplosrichtingen zijn:
- Twee (2) gelijktijdig gepubliceerde versies die een unieke en eenduidige versienummer hebben;
- MMVerplicht
- MMOptioneel
- Nummering conflicteert niet tussen MMVerplicht en MMOptioneel (beide zijn en blijven uniek identificeerbaar)
- Beperken van R&A software changes (uit te voeren door de R&A leverancier).
- Beperken van de URL aanpassingen door de deelnemers voor de specifieke end-points.
NEN 7522-2021
3.20 Versiebeheer
Vastleggen en archiveren van aangebrachte wijzigingen en ontwikkelingen tussen verschillende opvolgende versies.
Opmerking: bij de term: "Sommige versies zijn ook een release."
Een release is een versie met een officiëlere status. Bijvoorbeeld 'Definitief', 'In consultatie' en om die reden ook vrijgegeven voor een breder publiek. Tussenliggende versies worden gebruikt tijdens het ontwikkelen van de standaard of het stelsel van standaarden en vallen ook onder het versiebeheer.
6.5.6 Eisen aan de stelseldistributeur
De stelseldistributeur is minimaal verantwoordelijk voor het bekendmaken van de artefacten in het stelsel van standaarden bij alle geïnteresseerde en betrokken partijen.
a) De stelseldistributeur moet er voor zorgen dat een versie van een artefact van het stelselmanagement een unieke identificatie heeft en dat duidelijk is aangegeven wat voor type publicatie het betreft (bijvoorbeeld prepublicatie, publicatie of patch). De unieke identificatie van de versie en het type publicatie wordt door de functioneel beheerder bepaald.
Algemene Versioneringsregels
Een versiewijziging volgt de wijziging met de grootste classificatie;
Een incompatibele wijziging leidt ALTIJD tot een major publicatie. (When you need to release a breaking change—any breaking change—you do it in a major version. )
Een compatibele wijziging KAN, met valide reden, ook tot een major publicatie leiden. (bv door major impact op de uitwisselingsketen)
Dit moet expliciet kenbaar worden gemaakt in de communicatie.
ref: Nictiz Duurzaam Releasebeleid versie 1.0.0-bèta
Hoe moet ik omgaan met uitgefaseerde functionaliteit?
Het uitfaseren van bestaande functionaliteit is een normaal onderdeel van softwareontwikkeling en is vaak vereist om voortgang te maken. Als een deel van je publieke API uitgefaseerd wordt, dienen er twee dingen te veranderen:
(1) werk documentatie bij zodat gebruikers op de hoogte zijn van de wijziging,
(2) breng een nieuwe mineurversie uit waaruit duidelijk wordt dat de functionaliteit wordt uitgefaseerd. Voordat je met een majeure versie de functionaliteit helemaal verwijdert, dient er tenminste één mineurversie uitgebracht te zijn die duidelijk maakt dat de functionaliteit wordt uitgefaseerd, zodat gebruikers een soepele overgang hebben naar de nieuwe API.
ref: https://semver.org/lang/nl/
Definitie compatibiliteit:
Twee versies van een standaard (stelsel) zijn compatibel met elkaar als een implementerend systeem kan overstappen van de ene naar de andere versie of gegevens kan uitwisselen met een systeem dat de andere versie implementeert, zonder dat er aanpassingen nodig zijn en zonder dat er problemen ontstaan door wijzigingen in de nieuwe versie.
Als een nieuwe versie compatibel is met een eerdere versie, wordt er gesproken over backward compatibiliteit.
Als er een eerdere versie compatibel is met de nieuwe versie, wordt er gesproken over forward compatibiliteit.
ref: Nictiz Duurzaam Releasebeleid versie 1.0.0-bèta
Duiding van change | Classificatie |
|---|---|
| Stelselovergang van Optioneel naar Verplicht en de introductie van de nieuwe Optionele stelselversie. | NVT |
Niet backward compatibel publicatie (Core Stelsel, Extensie en of gegevensdiensten inclusief R&A) Een niet backward compatible MedMij stelsel aanpassing is bijvoorbeeld het introduceren van een nieuwe Core rol of functie (of het verplaatsen van een Extensie functie naar Core functie). | Major |
Compatibel publicatie (Core stelsel, Extensies en of Gegevensdiensten inclusief R&A blijft compatibel) Een backward compatible MedMij stelsel aanpassing is bijvoorbeeld het introduceren van een nieuwe Extensie rol of functie of aanvullingen op operationele processen, beleid en Normenkader. | Minor |
Correcties (Patch) is een tussentijdse publicatie met niet functionele aanpassingen en/of tekstuele correcties of verduidelijkingen. | Patch |
Aannames
- Versieovergang van Optioneel naar Verplicht volgen de gezamenlijk (jaarlijks) vastgestelde release moment(en).
- Major en Minor aanpassingen volgen een gezamenlijk vastgesteld release moment.
- Patch aanpassingen volgen een vast maandelijks (optioneel) releasemoment.
- Op de verplichte stelselversiepublicatie wordt geen major aanpassingen doorgevoerd tenzij (bv op basis van security, regelgeving of major bug-fix).
- Op de verplichte stelselversiepublicatie wordt een minimum aan minor aanpassingen met functionele impact doorgevoerd. De scope van de verplichte functionaliteit blijft zover mogelijk gelijk (geeft wel de optie om bv extensie aan te passen).
- Op de verplichte stelselversiepublicatie kunnen patches met procedurele en tekst aanpassingen worden doorgevoerd. De scope van de functionaliteit blijft gelijk.
- Op de optionele stelselversiepublicatie wordt een minimum aan major aanpassingen doorgevoerd (bv op basis van security of regelgeving of bij directe grootte functionele meerwaarde).
- Op de optionele stelselversiepublicatie kunnen minor aanpassingen met functionele impact worden doorgevoerd. De scope van de verplichte functionaliteit blijft zover mogelijk gelijk
- Op de optionele stelselversiepublicatie kunnen patches met procedurele en tekst aanpassingen worden doorgevoerd. De scope van de functionaliteit blijft gelijk.
Stelselovergang van Optioneel naar Verplicht en de introductie van de nieuwe Optionele stelselversie.
Het overgaan van Optioneel naar Verplicht is op zichzelf geen 'change' van de inhoud. Dit is een status overgang.
Het kan natuurlijk wel dat bij de promotie van MMOptioneel naar MMVerplicht er ook nog een major, minor of patch gelijktijdig wordt doorgevoerd. Dan wordt het versienummer volgens de classificatie aangepast.
classificatie kader major, minor, patch
Uitwerking van de oplossingsrichtingen
Gedurende de uitwerking van de oplossingsrichting zijn de volgende scenario's besproken.
Oplossingsrichting 1
Hybride, Epoch (date) + SemVer (yyww-X.Y.Z)
yy= laatste 2 digits van de jaaraanduiding bv 22 voor 2022
ww= de weekaanduiding bv 03 voor week 3
Combinatie maakt unieke identificatie van 2 gepubliceerde versies mogelijk.
Door de toevoeging van de Epoch Date is er altijd een uniek startpunt voor een release versie met de volledige reikwijdte van de SemVer versienummering.
Gedurende de life cycle van deze release blijft het Epoch label onveranderd (en daarmee ook uniek). Ook bij de status overgang van Optioneel naar Verplicht.
Oplossingsrichting 2
Hybride, Release-label + SemVer (Release-n-X.Y.Z)
Combinatie maakt unieke identificatie van 2 gepubliceerde versies mogelijk.
Door de toevoeging van het Release-label is er altijd een uniek startpunt voor een release met de volledige reikwijdte van de SemVer versienummering.
Gedurende de life cycle van deze release blijft het Release-label onveranderd (en daarmee ook uniek). Ook bij de status overgang van Optioneel naar Verplicht.
Oplossingsrichting 3
Alleen SemVer (x,y,z)
Bij de uitwerking van V1 MO-30, Release Cycle Management is een van de scenarios het laten vervallen van de MMOptioneel. Dit betekend dat een van de uitgangspunten voor MO-6, Versioning van het afsprakenstelsel, het ondersteunen van twee active versies vervalt.
Dit levert een 3de oplossingsrichting voor versioning op waarbij we geen Epoch label nodig hebben, en gebruik kunnen maken van alleen de SemVer nummering.
Pre-release nummering
Om in Oplossingsrichting 3 het afsprakenstelsel door te ontwikkelen is een ontwikkelversie van het afsprakenstelsel nodig. Deze zal ook uniek identificeerbaar moeten zijn. SemVer ondersteunt dit in de vorm van een pre-release nummer.
Een prerelease-versie MAG worden aangeduid met de toevoeging van een koppelteken en een serie van puntgescheiden id’s direct volgend op de patchversie.
Id’s MOETEN slechts bestaan uit alfanumerieke ASCII karakters en koppeltekens [0-9A-Za-z-].
Id’s MOGEN NIET leeg zijn.
Voorloopnullen MOGEN NIET aanwezig zijn in numerieke id’s.
Prerelease-versies hebben een lagere prioriteit dan de bijbehorende reguliere versie. Een prerelease-versie impliceert instabiel te zijn en voldoet mogelijk niet aan de voorgenomen compatibiliteitseisen zoals aangeduid bij de bijbehorende reguliere versie. Voorbeelden: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.–.
Oplossingsrichting 4
Alleen SemVer (x,y,z) voor de MMVerplicht en SemVer-rc voor de MMOptioneel
Op basis van de werksessie/presentatie
De next major release candidate (-rc) is samengesteld op basis van opgeleverde stories (USM 'Wijzigen => Uitvoeren'). Waarbij het criteria 'Major impact op de comptabiliteit' leidend is.
Een Major wijziging moet minimaal 6 maanden als release candidate beschikbaar zijn (Tenzij, overmacht of gezamenlijk besluit om af te wijken).
Dit betekend dat wanneer een Major change ingepland wordt deze als release (major) candidate (-rc) gepubliceerd wordt met een (nieuw) major nummer en deze als 2de stelsel publicatie beschikbaar is.
Tegen de release candidate (-rc) kan vervolgens ontwikkeld en geaccepteerd worden. Op het geplande release moment wordt deze dan de huidige verplichte versie en kan een nieuwe release candidate geïntroduceerd worden. (Dit is grotendeels gelijk aan de huidige situatie).
- We gaan, in lijn met Nictiz, Semver als versienummering hanteren voor de verplichte X.Y.Z en de release candidate (-rc) X.Y.Z-rc hanteren.
- voor de MMVerplicht 6.0.0
- voor de MMOptioneel 7.0.0-rc
We houden hierbij de optie voor het dakpanmodel, waarbij de optionele versie nu de eerstkomende major release candidate (-rc) versie is.
- Major releases 2 x per jaar (dinsdag week 18 en week 44) tenzij overmacht of afspraak
- Minor releases 2 x per jaar (dinsdag week 18 en week 44) of in overeenstemming maandelijks (12 release sloten per jaar, 3de dinsdag)
- Patches release 12 x per jaar (12 release sloten per jaar, 3de dinsdag)
- We houden een overzicht bij van alle opgeleverde stories met hun impact classificatie en vastgestelde release slot.
- Een maand voor het major release slot wordt de release samenstelling (Major + Minor items) definitief vastgesteld.
- Acceptatie toetst op de dan geldende Major / minor versie (note: minors kunnen alleen in overleg tussentijd gepubliceerd worden)
- R&A alleen op de Major versie nummering labelen.
Advies oplossing:
De eerder voorgestelde oplossingsrichtingen paste niet voldoende in het voorgestelde release cycle management aanpassing (MO-30) Op basis hiervan is initieel voorgestelde gebruik te maken van oplossingsrichting 4.
Alleen SemVer (x,y,z) voor de MMVerplicht en SemVer-rc voor de MMOptioneel.
Dit voorstel is op besproken met het kernteam.
Op basis van de feedback is het volgende besloten en verder uitgewerkt als oplossing.
- Versie 1.6.0 (MMOptioneel) die in week 19 verplicht wordt blijft versie 1.6.0 houden (geen aanpassing in de nummering)
- Versie 1.7.0 aangepast naar versie 2.0.0 (ipv de voorgestelde 7.0.0)
- -rc gaan we niet opnemen in de nummering*
- ‘Vaste release moment’ maandelijks 2de dinsdag, echter het is geen probleem als dit een week voor of achteruit schuift bv bij week 19 de eerste dinsdag van de maand is (denk aan vakantieperiodes).
- R&A en stelsel nummering blijft voor versie 1.6.0 zoals deze nu gebruikt worden, de nieuwe nummering gaat in voor versie 2.0.0 (werk versie 1.7.0). Voor deze versie wordt dit dan Versie 2.
'* dit heeft een risico in zich dat we een overlap in nummering krijgen. Dit was in de uitwerking van dit onderwerp de aanleiding om een pre-fix op te nemen en later gelijk aan Nictiz de -rc post-fix.
We schatten in dat dit risico relatief klein is, en als dit voorkomt we een oplossingen bedenken door bijvoorbeeld een nummer over te slaan).
Impact/migratieplan R&A en DAP
Migratie plan voor de R&A
De R&A gebruikt API Versie nummer(s) om te duiden welke API verplicht en optioneel actief is voor uitwisseling. Dit is nu gebaseerd op de huidige MedMij stelselnummers.
Waarbij de laatste nummeraanpassing van 1.5.0 naar 1.5.1 niet in de R&A is aangepast. Reden hiervoor is dat alle opgenomen zorgaanbieder-gegevensdienst combinaties gekoppeld zijn aan het API nummer.
Een aanpassing betekend dat alle individuele opgenomen zorgaanbieder-gegevensdiensten opnieuw opgevoerd moeten worden door de deelnemers (ca 9000 voor de 1.5.x). Bij de nummeraanpassing van 1.5.0 naar 1.5.1 gaf dit al de nodige 'misverstanden' tgv de mismatch tussen stelselnummer en API nummer. Om dit naar de toekomst toe te voorkomen is het voorstel om alleen het major versie nummer als label op te nemen. Dit in combinatie met de overgang naar de SemVer versienummerring (best practice).
Status 10 jan 2023
Voor de aankomende release versie 1.6.0 (R&A nummering) zijn er reeds een groot aantal zorgaanbieder-gegevensdiensten opgenomen onder de API 1.6.0.
Denk ook aan de API-nummers die in de diverse URL's zijn opgenomen (aan de aanbieder-kant!) maw, alleen in de R&A aanpassen geeft nog steeds een hybride beeld (oud en nieuwe nummers in een data set)
<Interfaceversie>
<InterfaceversieId>1.6.0</InterfaceversieId>
<Gegevensdiensten>
<Gegevensdienst>
<GegevensdienstId>49</GegevensdienstId>
<AuthorizationEndpoint>
<AuthorizationEndpointuri>https://medmij-inlog.vzvz.nl/1.6.0/oauth2/authorize</AuthorizationEndpointuri>
</AuthorizationEndpoint>
<TokenEndpoint>
<TokenEndpointuri>https://medmij-pgo.vzvz.nl/1.6.0/oauth2/token</TokenEndpointuri>
</TokenEndpoint>
<Systeemrollen>
<Systeemrol>
<Systeemrolcode>MM-2.0-HGB-FHIR</Systeemrolcode>
<ResourceEndpoint>
<ResourceEndpointuri>https://medmij-pgo.vzvz.nl/1.6.0/fhir/stu3/49</ResourceEndpointuri>
</ResourceEndpoint>
</Systeemrol>
</Systeemrollen>
</Gegevensdienst>
Er wordt in de R&A dus op 2 manieren verwezen naar de stelselversienummers via het API Versie label en in de (door de deelnemers) opgevoerde URL's.
Dit zie je ook terug in de ZAL/ZKL/OCL/WHL
Het alleen aanpassen van de API versie (label) naar versie V-6 levert dan een 'mismatch' tussen de reeds opgevoerde URL versie referenties (zie bovenstaande URL voorbeelden)
- Er is besloten dat we de huidige versie 1.6.0 behouden zoals deze nu al gepubliceerd is en in de R&A is opgenomen (inclusief alle verwijzingen.
- Er is besloten dat we de eerstvolgende versie (1.7.0) als versie 2.0.0 en in de R&A als versie 2 gaan opnemen (dit is de voorgenomen release 2023, week44).
- analyse waar dit in het afspraken stelsel beschreven staat
Verschillende typen releases, en correcties
Aanpassen van de Major-Minor beschrijving nodig toevoegen Patch beschrijving Tabel actualiseren van de release versie en inhoud.
1.6.0 => 2.0.0
DAP
De DAP (Dossier Afspraken en Procedures) is ook gekoppeld aan het stelselversienummer.
Ook hier kijken naar de mogelijkheid om bij de DAP alleen te verwijzen naar het Major release nummer.
** dit zou ook de optie geven om los van de stelsel versie de minor en patch van de DAP nummering te koppelen aan de interne revisie cyclus van de DAP vanuit keten-regie.
maw het major nummer = stelselversienummer en minor-patch is Keten-regie revisies.
- Bespreken met Stefan van Thie
- Er is besloten dat voor de versie van de DAP alleen naar het Major release nummer wordt verwezen (los van het versiebeheer op de DAP).
Ook hier vindt de overgang getrapt plaats, versie 1.6.0 blijft zoals nu benoemd, versie 1.7.0 wordt DAP versie 2 (2.0.0 beoogde release 2023 week 44). - Er is besloten dat vanuit het afspraken stelsel (beleid) een link op te nemen naar een vaste Medcom pagina, deze is voor aspirant en actieve deelnemers toegankelijk (achter Medcom login, niet publiek).