1. Probleemstelling

Doordat we oplopende versienummers combineren met twee gepubliceerde versies van het afsprakenstelsel, kunnen major en minor wijzigingen niet zomaar doorgevoerd worden. Op dit moment zijn 1.5.1 en 1.6.0 gepubliceerd. Een minor wijziging van 1.5.1 zou betekenen dat deze 1.6.0 zou moet krijgen, maar die bestaat al. Een major publicatie zou beide naar 2.0.0 brengen, ook dit is onwenselijk.

2. Wat willen we oplossen

Twee (2) gelijktijdig gepubliceerde versies met unieke versienummering die niet overlappend is.
De flexibiliteit om minor en correcties van het MedMij stelsel te publiceren (zonder noodzakelijke R&A versienummer update!).
Heldere criteria voor clasificatie Major, Minor of correctie (Huidige release nummering is niet consequent en voor correcties niet duidelijk in het versienummer).
Minder aanpassingen in de R&A tav Versienummers in URI’s en Gegevensdiensten (Alleen bij major release of major patch).
Wel traceerbaar en herkenbaar welk moment de publicatie heeft plaatsgevonden.

3. Huidige situatie

Twee (2) gelijktijdig gepubliceerde versies;

MMVerplicht 1.5.1
MMOptioneel 1.6.0
(Beide moeten eenduidig geïdentificeerd zijn)

In het /wiki/spaces/MMVerplicht/pages/132024128 staat het volgende vermeld:

Verschillende typen releases, en correcties

Releases voor het afsprakenstelsel worden als volgt aangeduid:

Major releases: releases met grotere (functionele) wijzigingen. Deze releases worden opgenomen in de releaseplanning;
Minor releases: releases met twee soorten correctief onderhoud:
1. Wijzigingen die nodig zijn om een onmiddellijke dreiging voor de continuïteit van of het vertrouwen in het MedMij Afsprakenstelsel/-netwerk af te wenden;
2. Verbeteringen waarvan de baten van spoedig doorvoeren significant groter zijn dan de implementatie-inspanningen, en die op breed draagvlak onder de deelnemers kunnen rekenen.

De aanduiding van releases is opgebouwd uit drie nummers, namelijk x.y.z (bijvoorbeeld 1.3.2). Bij een major release wordt de combinatie x.y opgehoogd. Daarbij zijn twee opties, ofwel y wordt met een verhoogd waarna z op 0 wordt gezet (bijvoorbeeld van 1.3.2 naar 1.4.0), ofwel x wordt met een verhoogd waarna y en z op 0 worden gezet (bijvoorbeeld van 1.3.2 naar 2.0.0). De keuze hiertussen is afhankelijk van aard en omvang van de release. Bij een minor release wordt z met een verhoogd (bijvoorbeeld van 1.3.2 naar 1.3.3).

Major release vinden twee maal per jaar plaats. De inhoud van een major release wordt samengesteld op basis van uitgewerkte wijzigingsvoorstellen (RFC's). Minor releases zijn niet bij voorbaat gepland; zij worden alleen indien nodig tussen major releases uitgebracht, op een datum die in overleg met Deelnemers wordt vastgesteld.

Daarnaast kunnen correcties op het MedMij Afsprakenstelsel worden aangebracht zonder dat deze leiden tot een nieuwe release. Deze doen bijvoorbeeld acute reparaties, verwijderen inconsistenties of passen voorbeeldberichten aan. Een correctie tast de juridische en technische strekking van het MedMij Afsprakenstelsel niet aan; waar dit wel het geval zou zijn, vereist de wijziging een nieuwe release. Correcties worden op een aparte pagina in het MedMij Afsprakenstelsel aangegeven.

3.1. Impact op R&A

De versienummering heeft ook een directie impact op de gebruikte URI registratie in de R&A stelsel node. Dit betekend dat zelfs bij een minor aanpassing x.y.1 => x.y.2 alle in de R&A opgenomen URI's ( aprox 9500 en groeiend) door de deelnemers (DVP en DVA) moeten worden aangepast.

We hanteren nu bij de 6 maandelijkse release cycle altijd een aanpassing van het versienummer, waarmee we, zelfs als er geen backward compatible breaking changes zijn, elke 6 maanden alle URI's moeten aanpassen. Ook wanneer we een kleine (minor) set van aanpassingen hebben bijvoorbeeld alleen een toevoeging van extensies en geen core functionaliteit hanteren we dit mechanisme. Resulterend in veel 'extra effort' voor een release die geen impact heeft op het functioneren van de huidige koppelvlakken.

4. Verkenning Opties

Voor de verkenning van de oplossingsrichtingen zijn de volgende uitgangspunten als voorwaarde opgenomen:

Twee (2) gelijktijdig gepubliceerde versies die een unieke en eenduidige versienummer hebben;
- MMVerplicht
- MMOptioneel
Mogelijkheid om tussen de vastgestelde 2 x per jaar formele release cycles een traceerbare minor publicatie door te voeren op één of beide gepubliceerde versies
Mogelijkheid om tussen de vastgestelde 2 x per jaar formele release cycles een traceerbare patch publicatie door te voeren op één of beide gepubliceerde versies
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 URI aanpassingen door de deelnemers voor de specifieke end-points (Elke versienummer aanpassing vraagt nu een een URI aanpassing.)

Duiding van change	Classificatie
Stelselovergang van Optioneel naar Verplicht en de introductie van de nieuwe Optionele stelselversie	Major
Niet backward compatibel publicatie (Core Stelsel en of gegevensdiensten inclusief R&A)	Major
Compatibel publicatie (Extensies, Core en Gegevensdiensten inclusief R&A blijft compatibel)	Minor
Correcties (tussentijdse) publicatie met niet functionele aanpassingen en tekstuele correcties.	Patch

Brainstorm:

4.1. Semantic Versioning (SemVer) (X.Y.Z)

Dit is de actuele nummer sequentie die wordt gebruikt, echter de Major nummering wordt niet volgens de SemVer standaard toegepast.

Voorbeeld : 1.5.1 => 1.6.0

Voor	Tegen
Software-industrie standaard manier van versienummering Major, Minor, Patch.	Met twee gepubliceerde versies gaan de gebruikte versienummers overlappen bij een Major update MMVerplicht 1.5.1 MMOptioneeel 1.6.0 Major update => MMVerplicht 2.0.0 en MMOptioneel 2.0.0. <= Geen unieke identificatie meer.
Dit is het huidige format wat we gebruiken.	In het huidige format gebruiken we de Minor als 'release versie ID' => release MMOptioneel okt 2022 wordt dan 1.7.0. We verliezen hierbij de optie om Minor en Patch publicaties te verwerken (Minor zou dan in de Patch ID geplaatst moeten worden.) geen extra digit voor Patch over.
	We hanteren nu voor de R&A de volledige ID string => 1.5.0 (De MMVerplicht versie van het stelsel is nu 1.5.1. De discrepantie tussen de laatste digit heeft veel vragen/onduidelijkheid opgeleverd)
	Bij elke aanpassing van SemVer nummer moet de R&A SW aangepast worden om de nieuwe versie te herkennen.
	Bij elke aanpassing van SemVer nummer moeten alle R&A URI's aangepast worden.

4.2. Epoch date based (yyyy-mm-dd)

Voorbeeld : 2022-09-23, 2022-11-04

Voor	Tegen
Gebruik van (Epoch) timestamp is een simpel nummering format.	Met twee gepubliceerde versies gaan de gebruikte versienummers overlappen bij een publicatie update op beide gepubliceerde versies MMVerplicht 1.5.1 MMOptioneeel 1.6.0 Update => MMVerplicht 2022-08-23 en MMOptioneel 2022-08-23 <= Geen unieke identificatie meer.
	(Epoch) timestamp geeft geen indicatie wat de impact is van de change (Major, Minor, Patch)
	Bij elke aanpassing van het (Epoch) timestamp moet de R&A SW aangepast worden om de nieuwe versie te herkennen.
	Bij elke aanpassing van het (Epoch) timestamp moeten alle R&A URI's aangepast worden.

4.3. Sequentiële nummering (n+1)

Voorbeeld : 1, 2, 3, 4.....

Voor	Tegen
Gebruik van Sequentieel nummer is een simpel nummering format.	Met twee gepubliceerde versies gaan de gebruikte versienummers overlappen bij een publicatie update op beide gepubliceerde versies MMVerplicht 1.5.1 MMOptioneeel 1.6.0 Update => MMVerplicht 2 en MMOptioneel 2 <= Geen unieke identificatie meer. Update MMOptioneel 2 => 3 =>4 => 5 Update MMVerplicht 2 => 3 => het nummer 3 is reeds uitgegeven aan MMVerplicht, geen unieke identificatie meer 4.3.1. Dit kan wel een optie zijn MEt het uitgeven van een Nummer aan een publicatie is het nummer 'uniek gealloceerd' voor de ze publicatie. (je krijgt dan een soort van haasje over) Dit zal de duidelijkheid van de nummering niet ten goede komen!
	Sequentieel nummer geeft geen indicatie wat de impact is van de change (Major, Minor, Patch)
	Bij elke aanpassing van het Sequentieel nummer moet de R&A SW aangepast worden om de nieuwe versie te herkennen.
	Bij elke aanpassing van het Sequentieel nummer moeten alle R&A URI's aangepast worden.

4.4. Hybride, Epoch (date) based + SemVer (yyyy-ww-X.Y.Z)

Voorbeeld : 2022-44-1.0.0, 2022-44-1.0.1 (Patch), 2022-44-1.0.2 (Patch), 2022-44-1.1,0 (Minor), 2022-44-2.0.0 (Urgent Major) => 2023-04-1.0.0 (Opvolgende Major stelsel release)

Voor

Tegen

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.
Gedurende de life cycle van deze release blijft dit deel constant (en daarmee ook uniek)

Complexere Versie-string format

Maakt onderscheid tussen Versie release (Major) en Major Patch mogelijk.

Bij Major publicatie is nog steeds in de R&A de aanpassing van alle URI's noodzakelijk!

Meer impact analyse nodig of een change Major / Minor is

Maakt het mogelijk om voor de R&A alleen de release-Major identificatie te gebruiken.

Stelsel	R&A
2022-44-1.0.0	2022-44-1
2022-44-1.0.1 (Patch)	2022-44-1
2022-44-1.0.2 (Patch)	2022-44-1
2022-44-1.1.0 (Minor)	2022-44-1
2022-44-2.0.0 (Urgent Major)	2022-44-2
2023-04-1.0.0 (Opvolgende Major stelsel release)	2023-04-1

Bij elke aanpassing van Hybride (basis) nummer moet de R&A SW aangepast worden om de nieuwe versie te herkennen

Bij Minor en Patch publicatie is geen R&A aanpassing van alle URI's noodzakelijk!

Eenmalige aanpassing van Versienummering van alle R&A URI's noodzakelijk.

Ook tekst correcties kunnen (zonder impact op comptabiliteit) kunnen nu in een standaard gecontroleerd change proces gepubliceerd worden, inclusief Patch-versienummer aanpassing (change traceability en verantwoording)

Ook een 'soft' introductie is een optie, we introduceren de nieuwe nummering op de eerstvolgende Major stelsel publicatie en hanteren voor de huidige transitie van 1.6.0 naar MMVerplicht de actuele 1.6.0 notatie.

Voorbeeld van deze vorm van nummering : https://wiki.ubuntu.com/Releases

4.4.1. Extra Optie

ipv een Epoch datum kan er ook voor een publicatie-versie gekozen worden.

Bij elke nieuwe stelsel (major) release wordt dan een publicatie-versie gebruikt (deze blijft uniek voor deze versie, ook in de overgang van optioneel naar verplicht)

Stelsel	R&A
Publicatie-7-1.0.0	Publicatie-7-1
Publicatie-7-1.0.1 (Patch)	Publicatie-7-1
Publicatie-7-1.0.2 (Patch)	Publicatie-7-1
Publicatie-7-1.1.0 (Minor)	Publicatie-7-1
Publicatie-7-2.0.0 (Urgent Major)	Publicatie-7-2
Publicatie-8-1.0.0 (Opvolgende Major stelsel release)	Publicatie-8-1

Dit lijkt in grote mate op de nieuwe methodiek die ook Nicitiz gaat toepassen op de MM-gegevensdiensten.

(Publicatie of Versie of Release)?

5. Bronvermelding

Duurzaam Releasebeleid (concept Versie 0.3 | mei 2022), Nictiz
https://wiki.ubuntu.com/Releases
https://flowcanon.com/software/versioning-strategy/
https://semver.org/

Browser not supported