Als beheerder wil ik een nieuwe versie van een referentie-implementatie kunnen uitrollen

[melsk-r]

...zodat ik in staat ben om direct bij de publicatie van een nieuwe versie van een Open API standaard ook de bijbehorende versie van de referentie implementatie uit te rollen.

Definition of ready

• [x] Iedereen in het team begrijpt de user story
• [x] Is klein genoeg voor een sprint
• [x] Product Owner akkoord en voorzien van prio
• [x] Voorzien van Acceptatiecriteria
• [x] Voorzien van Definition of Done
• [x] Voorzien van taken
• [x] Vastgelegd Github en in geplaatst in kolom ready for sprint

Definition of done

Algemeen

Een werkwijze/middel/tools om ZDS-API goed in beheer te nemen.

Specifiek

• [ ] De wijze waarop een referentie-implementatie wordt uitgerold wordt beschreven in een procedure zodat men daarop kan terugvallen;
• [ ] Een beheerder moet in staat zijn zelfstandig een aangepaste versie van een referentie implementatie uit te rollen (Zie ook #60 en #61).
• [ ] ...

Oplossingsrichting

Beschrijf hoe uitrol in zijn werk gaat en pas dit toe in een testomgeving....

Acceptatiecriteria

• [ ] Niet belemmerend werken voor beheer andere standaarden;
• [ ] Er is een beschrijving hoe de referentie-implementatie uitgerold moet worden;
• [ ] De beheerder(s) zijn aantoonbaar in staat om een referentie implementatie uit te rollen.

Taken

• [ ] Docker installeren (@melsk-r @michielverhoef)
• [x] Procedure (@melsk-r)
• [x] Initiële aanlevering Demo-Docker met inhoud (@joeribekker)
• [ ] DEMO-CI straat aanleveren (@joeribekker)
• [ ] Oefenen met in beheer nemen (@melsk-r @michielverhoef)
• [ ] Oefenen met zelf wijziging in specificaties opnemen (@melsk-r @joeribekker, @michielverhoef)
• [ ] beheersrechten (@melsk-r @joeribekker @michielverhoef)

[melsk-r]

Docker is geïnstalleerd op mijn laptop maar levert problemen op voor de activatie van de WIFI. Een probleem dat opgelost moet worden aangezien op de VNG laptops geen vaste netwerkkaart aanwezig is.

[michielverhoef]

Op mijn laptop is het ook niet mogelijk om de docker containers te benaderen. Het lijkt er op dat Docker niet benaderbaar is via de in de documentatie beschreven manieren.

[TCIMEddy]

@melsk-r @michielverhoef Als het een impediment is maak er dan ajb apart een impediment voor aan.

[melsk-r]

Ik denk dat we eerst moeten kijken of we het echt niet aan de praat krijgen. Is dat het geval dan wordt het n.m.m. pas een impediment. Nu is het een technisch probleempje dat opgelost moet worden en dat misschien het tijdig afronden van dit issue in de weg staat.

[melsk-r]

Docker werkt inmiddels bij mij.

@joeribekker Kan jij z.s.m. de volgende 2 taken uitvoeren zodat Michiel en ik de inmiddels door mij beschreven procedure kunnen testen en aanscherpen.

@michielverhoef Wat bedoel je met dat je de Docker containers niet kunt benaderen. In het kader van het beschrijven van de procedure heb ik zelf een Docker image op DockerHub geplaatst en deze kan ik gewoon runnen. Ik neem echter aan dat je wat anders bedoelt. Als je Docker al wel geinstalleerd hebt en dat werkt kan je dan die taak hierboven aanvinken?

[joeribekker]

Voortgang hier: https://github.com/maykinmedia/demo-api-component

[joeribekker]

API spec hier, incl patch release en versie informatie: https://github.com/maykinmedia/demo-api

[joeribekker]

Er komt nog een versie 2.0.0, 2.1.0 en 2.1.1 met wijzigingen om direct het versie-beheer helder te krijgen.

[joeribekker]

Meh, Github lag er even uit en toen was mijn comment weg

Even de kort het idee:

1. Je kan de semantische wijzigingen bekijken in de Changelog
2. Je kan van elke versie apart de specificaties bekijken, zoals van versie 1.0.0 en versie 1.0.1
3. Je kan versies van de specificatie echt met elkaar vergelijken (bijvoorbeeld 1.0.0 vs 1.0.1):

Qua versies verder heb ik even een suggestie gedaan in de README. kort samengevat:

• Een major versie update (bijv. van 1.x naar 2.x) bevat breaking changes t.o.v. de vorige versie.
• Een minor versie update (bijv. van 1.0.x naar 1.1.x) bevat inhoudelijke wijzigingen aan de API die geen breaking changes betreffen.
• Een patch versie update (bijv. van 1.0.0 naar 1.0.1) is een minimale wijziging die geen inhoudelijke wijziging betreft maar voornamelijk bedoeld is voor documentatie wijzigingen.
• Elke major API versie krijgt minimaal 1 jaar ondersteuning vanaf de release datum van de volgende major API versie.

[joeribekker]

Tevens ook laten zien dat we direct rekening houden met hoe we van 1.0.1 naar 2.0.0 migreren, in de Changelog. Dit geeft aan dat het nieuwe verplichte veld "bronNaam" de waarde "(Onbekend)" krijgt voor bestaande records.

[joeribekker]

2.1.0 bij deze gedaan. Hier laat ik het bij.

[melsk-r]

Issue #61 is hiermee gelieerd.

[joeribekker]

Docker images: https://cloud.docker.com/u/vngr/repository/docker/vngr/demo-api

[michielverhoef]

Op mijn (nieuwe) laptop ben ik tegen het bekende docker-wifi probleem aangelopen. Jammer genoeg is het niet gelukt om dit op te lossen (ook niet met behulp van de verschillende hints en tips). De enige manier om wifi werkend te krijgen op deze laptop is docker uitschakelen en te deinstalleren. Ongetwijfeld heeft het iets met de wifi drivers te maken maar ik kan niet vinden wat.

Inmiddels heb ik begrepen dat vanuit de common ground projecten een gehoste omgeving voor Docker beschikbaar gaat komen waar wij docker containers kunnen draaien. Details hierover moeten we nog krijgen maar dat zou deze uitdaging voor ons oplossen.

[michielverhoef]

@joeribekker wrote:

• Een major versie update (bijv. van 1.x naar 2.x) bevat breaking changes t.o.v. de vorige versie.
• Een minor versie update (bijv. van 1.0.x naar 1.1.x) bevat inhoudelijke wijzigingen aan de API die > geen breaking changes betreffen.
• Een patch versie update (bijv. van 1.0.0 naar 1.0.1) is een minimale wijziging die geen inhoudelijke > wijziging betreft maar voornamelijk bedoeld is voor documentatie wijzigingen.
• Elke major API versie krijgt minimaal 1 jaar ondersteuning vanaf de release datum van de volgende major API versie.

Of een wijziging een breaking change is hangt af van de partij die de wijziging wel heeft geimplementeerd. Als een minor een wijziging bevat die door een provider nog niet ingebouwd is kan dit voor een consumer een breaking change zijn wanneer deze de wijziging wel gebruikt.

We moeten ook nog iets beslissen over het versiebeleid van "de vorige versie". Brengen we dan nog minors uit? Of alleen patches? Wat doen we dan met kritieke fouten?

[joeribekker]

Of een wijziging een breaking change is hangt af van de partij die de wijziging wel heeft geimplementeerd. Als een minor een wijziging bevat die door een provider nog niet ingebouwd is kan dit voor een consumer een breaking change zijn wanneer deze de wijziging wel gebruikt.

Nee! @johanboer noemde dit inderdaad 2 weken geleden maar dit is niet hoe het werkt.

Ik kan er hier wel over uitweiden, maar version negotiation e.d. staat prima beschreven in de API strategie (2.6.4 Versionering): https://aandeslagmetdeomgevingswet.nl/digitaal-stelsel/technisch-aansluiten/standaarden/api-uri-strategie/

We moeten ook nog iets beslissen over het versiebeleid van "de vorige versie". Brengen we dan nog minors uit? Of alleen patches? Wat doen we dan met kritieke fouten?

"Kritieke" fouten moeten worden opgelost, wat er ook voor nodig is, zolang de versie wordt ondersteund of het komt in de nieuwe versie.

Dus als dat een ontbrekende DELETE operatie is, moet deze middels een minor update op alle ondersteunde versie worden toegevoegd. Als het breaking is, dan komt hij alleen in de major update.

[michielverhoef]

Nee! @JohanBoer noemde dit inderdaad 2 weken geleden maar dit is niet hoe het werkt.

Ik kan er hier wel over uitweiden, maar version negotiation e.d. staat prima beschreven in de API strategie (2.6.4 Versionering): https://aandeslagmetdeomgevingswet.nl/digitaal-stelsel/technisch-aansluiten/standaarden/api-uri-strategie/

De DSO API en URI strategie zijn geschreven vanuit het gezichtspunt dat een basisregistratie de provider is. De basisregistratie bepaalt daarmee de versie van de API die dan beschikbaar is.

Dit geldt niet voor standaarden zoals de ZGW standaard. De providers zijn in dit geval producten gemaakt door leveranciers en uitgerold bij gemeenten. Het kan dus wel degelijk voorkomen dat een provider achter loopt ten opzichte van een consumer.

Versionering zoals beschreven in de API strategie beschrijft dus naar mijn mening niet correct hoe het werkt met standaarden en deze paragraaf zou uitgebreid moeten worden. Een taak voor @HenriKorver lijkt mij?

Edit: gezien de gevolgen van een wijziging zijn eigenlijk alle wijzigingen anders dan tikfouten in de documentatie breaking dus major.

[joeribekker]

Edit: gezien de gevolgen van een wijziging zijn eigenlijk alle wijzigingen anders dan tikfouten in de documentatie breaking dus major.

Nee (oftewel: ik deel deze conclusie niet)! Een consumer die een nieuwere versie praat dan de provider, en daarom een optioneel veld bijvoorbeeld niet wordt opgeslagen in de provider, daar moet de consumer mee om kunnen gaan (het is immers optioneel). Je noemt dit dus niet een breaking change. Als de consumer wel breekt, dan is de consumer slecht gemaakt.

Het kan dus wel degelijk voorkomen dat een provider achter loopt ten opzichte van een consumer.

Ja, maar dat is dus niet perse erg!

Een consumer die zeg maar Zaken API 1.1 praat, kan prima communiceren met een provider die Zaken API 1.0 praat. De consumer is compatible met 1.x. Het is echter wel van belang dat een consumer het versie nummer van de provider weet en aan version negotiation doet.

Als je argument is: maar de consumer krijgt dat optionele veld (uit hierboven genoemd voorbeeld) niet terug van de oudere provider. Dat klopt! Maar omdat het veld optioneel is moet de consumer ook niet verwachten dat hij altijd maar dit veld krijgt. Again: version negotiation.

Ik wil het wel aantonen met demo-api-consumer als dat echt nodig is...

[michielverhoef]

Daar ben ik het weer grondig niet mee eens. Wanneer een consumer een gegeven op wil slaan in een registratiecomponent moet de consumer er op kunnen vertrouwen dat dit gegeven later ook weer opvraagbaar is.

De redenering dat een optioneel veld niet ondersteund hoeft te worden door een provider is klink-klare nonsens. Eenzelfde issue hebben we eens met een grote leverancier gehad die bij de naam het tussenvoegsel niet opsloeg omdat dit een optioneel veld was. Dus in de consumer heette iemand Jan van Dalen en in de provider werd dat ineens Jan Dalen.

Dat is pertinent niet iets wat door een consumer opgevangen moet kunnen worden! Dat leidt tot fouten en zoiets moet duidelijk zijn voor de consumer.

Mijn punt is dat een consumer er op moet kunnen vertrouwen dat alles wat aangeboden wordt ook opgeslagen wordt in het registratiecomponent. Als dat niet zo is (en je dus maar af moet wachten wat je terug krijgt) is de standaard niet werkbaar omdat de opgeslagen gegevens niet betrouwbaar zijn. Bevragen bij de bron wordt dan een hachelijke zaak...

Optioneel betekent niet dat een gegeven gewoon weggelaten mag worden. Optioneel betekent dat een gegeven niet altijd beschikbaar is, bijvoorbeeld zoals een tussenvoegsel, en daarom niet verplicht in een bericht aanwezig hoeft te zijn. Maar als het aangeleverd wordt moet het wel opgeslagen en weer opgevraagd kunnen worden.

Je zou kunnen stellen dat alle gegevens verplicht zijn voor een provider, de provider moet alle gegevens kunnen afhandelen. Alleen zijn niet altijd alle gegevens aanwezig in een bericht. Dit kan overigens ook zijn omdat het gaat om afgeleide gegevens, bijvoorbeeld een datum waarop een zaak de eindstatus bereikt of waarop een object opgeslagen is.

[joeribekker]

Helaas heb ik het blijkbaar niet goed uitgelegd want ik zie verkeerde voorbeelden en onwaarheden (verkeerde interpretaties van zinnen).

Ik heb mijn visie, mening en feiten gegeven. Ik zie graag je versionering en ondersteuningsvoorstel tegemoet. Anders maar een keer face-to-face over babbelen.

[michielverhoef]

Onwaarheden zou ik het zeker niet willen noemen ...

Ik heb ook mijn visie, mening en feiten gegeven. Helaas is het zo dat deze gebaseerd zijn op situaties die we nu aantreffen bij gemeenten, ik verzin ze niet.

Een goede discussie ga ik niet uit de weg maar alleen zeggen dat iemand verkeerde voorbeelden en onwaarheden aandraagt terwijl je eigen voorstel juist problemen in de hand gaat werken vind ik riskant.

Laten we hier snel maar eens met elkaar over doorpraten. Want ik begin me toch zorgen te maken...

[ehotting]

https://semver.org beschrijft het allemaal vrij precies

[michielverhoef]

Dat stuk ken ik maar licht alleen toe hoe je versies en versienummer opbouwt. Het laat niet zien waarom een versie major dan wel minor is.

Deze discussie gaat voornamelijk over wat een backwards incompatible wijziging is. Daar verschillen Joeri en ik van mening over.

[melsk-r]

Dat stuk ken ik maar licht alleen toe hoe je versies en versienummer opbouwt. Het laat niet zien waarom een versie major dan wel minor is.

Deze discussie gaat voornamelijk over wat een backwards incompatible wijziging is. Daar verschillen Joeri en ik van mening over.

@joeribekker , @michielverhoef: Zou goed zijn als we op dit punt de neuzen allemaal naar dezelfde kant hebben staan en daarom goed om de discussie te voeren als we elkaar recht in de ogen kunnen kijken. Dan kunnen we elkaar ook net even beter het waarom van onze standpunten uitleggen. Ik neem aan dat Johan maandag ook weer aanwezig zal zijn in Utrecht en ik stel voor om de dscussie dan te voeren en hem daarbij uit te nodigen. Eens?

[melsk-r]

De discussie over versiebeheer hoort trouwens niet in dit issue thuis aangezien dit gaat over hoe je een nieuwe versie van de referentie implementatie moet uitrollen. De discussie past veel beter in issue #32 of #25.

[michielverhoef]

Ik denk dat we goed moeten omschrijven wat met de deeltaak "Oefenen met in beheer nemen" bedoeld wordt want ik weet nu niet goed wat de bedoeling is.

[TCIMEddy]

@melsk-r Dus a.s. maandag gaan jullie het niet hebben over deze user story, maar algemene uitspraak en beleid over versiebeheer. Hoe ga je verder om met deze user story?

[michielverhoef]

Ik denk dat we goed moeten omschrijven wat met de deeltaak "Oefenen met in beheer nemen" bedoeld wordt want ik weet nu niet goed wat de bedoeling is.

Dit blijft wat mij betreft nog staan, ik weet niet wat met deze stap bedoeld wordt...

[melsk-r]

@TCIMEddy @michielverhoef @joeribekker : Volgens mij is het niet meer dan het oefenen hoe we een Referentie Implementatie (RI) met Docker/Kubernetes in de gewenste omgeving beschikbaar kunnen stellen. Daarvoor kunnen we de demo applicaties van Joeri gebruiken. Vooralsnog gaan we er vanuit dat we het beheer van RI's in regie uitvoeren. Zelf passen we dus niets aan. De vraag is dus of taak 'Oefenen met zelf wijziging in specificaties opnemen' van toepassing is. Is het wel realistisch er vanuit te gaan dat er situaties voorkomen waarbij we alleen een nieuwe versie van een RI uitrollen?

[melsk-r]

@TCIMEddy Wat is de reden dat je dit issue gesloten hebt? Het kunnen uitrollen van een RI (en wellicht ook andere componenten van een standaard is nog steeds van belang en dat moeten we oefenen. We hebben helaas nog niet aangetoond dat we dat beheersen.

[TCIMEddy]

@melsk-r stond in mijn aantekeningen :-) foutje sorry

[melsk-r]

@TCIMEddy Ah, ok. No problem.

[joeribekker]

@melsk-r Ik denk dat we deze US moeten aanscherpen of slicen. Ik zie in ieder geval niet in hoe we dit nu verder brengen dan dat wat we nu hebben.

[melsk-r]

@joeribekker Jij weet beter wat het betekent om de RI uit te kunnen rollen dus als jij denkt dat we beter dit issue kunnen slicen om het te kunnen handelen ga ik helemaal met je mee. Heb je ideeën hoe dit te slicen?

[joeribekker]

Maandag even overleggen.