Voorstel: beheer van schema's in Github

8 reacties / 0 nieuw
Rens Verhage
Voorstel: beheer van schema's in Github

In een andere discussie mbt Zaak- en documentservices (https://discussie.kinggemeenten.nl/discussie/gemma/stuf-zkn-310/datumsta...) heb ik de suggestie gedaan om het beheer van de StUF-schema's onder te brengen in een Github repository.

Volgens mij zijn daar goede argumenten voor. Het maakt beheer en onderhoud efficiënter en goedkoper, nodigt gebruikers van de standaarden uit om mee te ontwikkelen middels pull requests en het maakt het versiebeheer open en transparant.

Hier wat ik in de andere thread heb geplaatst:

Waar het ons als leverancier omgaat is transparantie en dan niet alleen in doorontwikkeling, maar ook in de samenhang tussen de verschillende deelproducten. Nu zijn het allemaal losse zip files. Als leverancier van een regiesysteem voor het sociaal domein worden we geacht verschillende vormen van te StUF ondersteunen: StUF-ZKN, StUF-BG, Zaak- en documentservices, Regie- en zaakservices en StUF-Jeugdzorg (CORV). Allemaal zijn ze te downloaden in een eigen zip file met een eigen versie.

Buiten deze bestanden is er nog een StUF 3.01 zip file te downloaden waarvan periodiek een patch level wordt uitgebracht. De samenhang tussen al die bestanden en en versies is niet transparant. Een publieke Git repository met daarin de volledige standaard inclusief alle eindproductstandaarden en een duidelijk model van branching en tagging (Git flow?) zou daarin het nodige aan duidelijkheid verschaffen.

In mijn vorige reactie noemde ik al het voordeel van pull requests waarbij leveranciers bugs of wensen als pull request in kunnen dienen. Het is dan een kwestie van een druk op de knop om zo'n wijziging upstream mee te nemen. Dat scheelt tijd en zorgt ervoor dat je sneller patches kunt uitrollen. Met zijn allen houden we de kwaliteit hoog. Doordat je met berichten op pull requests kunt reageren houd je codewijzigingen en discussies bij elkaar.

De combinatie van code repository, pull requests, wiki en issue tracker zoals Github dat biedt (maar bijvoorbeeld ook Bitbucket of Gitlab), maakt dat je niet een aparte issue tracker, een website met downloads, een discussieforum en je achterliggende code repository (-ies?) handmatig moet onderhouden.

Ik ben benieuwd of er meer voorstanders zijn van een dergelijke werkwijze. Zoals in de quote te lezen zijn er andere diensten die een soortgelijk model bieden, echter lijkt Github een logische keuze aangezien er reeds een organisatie KINGgemeenten op Github bestaat :)

Michiel Verhoef

Het laatste argument vind ik helaas het minst inhoudelijke. In Engeland rijden ze links maar toch, het is geen reden om nu ook maar aan de linkerkant van de weg te gaan rijden  :-)

Over dit verzoek kan ik vrij kort zijn: In onze "nieuwe aanpak" methode waarbij de koppelvlakken gemodelleerd worden in Enterprise Architect en hieruit bericht schema's gegenereerd worden met Imvertor kunnen we alleen gebruik maken van Subversion. Daar kun je hele discussies over houden maar dat is wat Enterprise Architect ondersteunt. Voor onszelf zou GitHub dus extra werk betekenen, niet alleen voor KING maar ook voor de andere gebruikers van Imvertor (waaronder Kadaster en GeoNovum). 

Daarnaast is snelheid van uitrollen geen vereiste op het vlak van standaardisatie: De laatste versie van de Zaak- Documentservices (ZDS 1.2) is van zomer 2016. Bij de vorige bijeenkomst op 17 oktober 2017 is gebleken dat slechts 2 leveranciers (waaronder een nieuwkomer, die telt eigenlijk niet mee in deze berekening) deze versie ingebouwd hebben. De overige leveranciers hebben deze versie nog niet ingebouwd en zelfs niet op de planning staan. (...!). We kunnen dus wel heel snel versies van standaarden gaan maken maar voor de interoperabiliteit is dat geen gunstige ontwikkeling. Een standaard moet ingebouwd, zowel bij providers als consumers, en uitgerold worden bij gemeenten. Eerlijk gezegd verwacht ik niet dat alle leveranciers een nieuwe versie van een standaard (te)gelijk doorvoeren en meteen uitrollen.

Het model van Topicus is anders dan dat van de meeste leveranciers, voor zover ik weet. Bij software die bij de gemeente zelf draait is men echt niet zo blij met elke paar weken een update.

Wat ik in je verzoek voornamelijk lees is meer duidelijkheid over de onderlinge samenhang tussen de verschillende StUF schema's ed. Met de nieuwe aanpak waarbij alleen nog maar eindproducten (koppelvlakken) beschikbaar komen als compleet geheel (dus zonder onderliggende StUF schema's die weer apart meegenomen moeten worden) is dit probleem denk ik opgelost.

Ik zeg niet dat alles nu perfect loopt en ik verwelkom alle voorstellen tot verbetering. Maar dit voorstel is volledig gedaan vanuit de zienswijze van een ontwikkelaar van een SAAS oplossing, niet vanuit standaardisatie oogpunt of het belang van gemeenten.

Voor de rest blijft wat mij betreft nog steeds mijn antwoord uit het vorige draadje gelden:

Ik heb niets tegen GIThub maar zie de voordelen of verschillen niet echt. Als ik kijk naar de Zaak- Documentservices zit eea. nu zo in elkaar:

De huidige schema's (laatste release, deze is geldig) staat op GEMMA Online. Deze release is vastgesteld door de werkgroep
Ontwikkeling gebeurt op basis van ingebrachte meldingen en wensen van zowel leveranciers als gemeenten. Deze onderhoudsverzoeken staan op https://kinggemeenten.plan.io/projects/zaak-en-documentservices/issues

Vanuit de werkgroep heb ik het signaal van behoefte aan een GIThub/development branch om verder te ontwikkelen nog niet gekregen. Sterker nog, er zijn nog wel wat partijen die de huidige versie nog moeten inbouwen... Ik vraag me dan ook serieus af hoeveel animo er is voor zoiets. Mocht er een partij zijn die deze werkwijze wel ziet zitten zie ik de aanmelding voor de werkgroep graag tegemoet!

 

Εelcο Ηοtting

Voor Haarlem is het niet te doen om te co-creëren in een werkgroep waar je fysiek met een aantal mensen om tafel zit, elkaar overtuigt in proza en dan een tijd wacht totdat de ingebrachte eisen en wensen zijn verwerkt is in Word documenten. De mensen die het beste aan deze standaarden kunnen werken drukken zich liever uit in code. Voorstel? Doe een Pull Request. Idealiter in een volwaardige CI/CD omgeving zodat we kunnen zien wat de consequenties zijn voordat we iets vaststellen. Ik begrijp dat een dergelijke aanhaking op de moderne tijd een vrij radicale wijziging is, maar het is wel wat nodig is om developers weer over de standaarden te laten meedenken.

Cathy Dingemanse

Ben het eens met Rens en Eelco. De reactie van Michiel wekt de indruk dat er de afgelopen jaren niets is gebeurd. Geen SIG rapport, geen conferentie, geen nieuwe standaard RSGB bevragingen, niets van dat alles. De noviteiten en handigheidjes uit de nieuwe standaard zijn immers waar mogelijk gekopieerd naar de oude standaard, dus we kunnen gewoon door op de oude vertrouwde weg.  

Terwijl we toch allemaal heel goed weten dat de kracht van de nieuwe standaard niet zit in de nieuwe handigheidjes, protocollen en architectuurstijlen. Want die zijn over een jaar (of wat) met 100% zekerheid achterhaald. Waar het echt om gaat bij de nieuwe standaard is DE AANPAK. Het is de aanpak die er voor zorgt dat we nooit meer in een situatie geraken zoals in het SIG rapport is geschetst (#never again).

Zo lang de standaarden waar het om gaat in meer dan 300 gemeenten moeten worden geïmplementeerd,  draait het er om de implementatiekosten en doorlooptijd BIJ GEMEENTEN laag te houden, en niet bij KING, Geonovum  of het Kadaster. Zie hier de belangrijkste doelstelling voor diegenen die belast zijn met de ontwikkeling van de standaarden voor gemeenten.

Naast een scherpe definitie van de gemeentelijke behoefte is de bruikbaarheid van de standaard, waaronder codegeneratie, een van de belangrijkste manieren om dit doel te bereiken. De aanpak van RSGB bevragingen is evidence based, dat betekent dat iedere claim wordt gevalideerd met testcode (in .NET en Java). Dit is niet leuk en hip, maar een absolute NOODZAAK om de kwaliteit van de standaard te behouden. Je kunt je afvragen of KING qua kennis, capaciteit en tooling in staat is om dat allemaal alleen te doen. Los van het antwoord op deze vraag, kan ik n.a.v. mijn ervaringen in het RSGB bevragingen traject met zekerheid zeggen dat een heleboel leveranciers en gemeenten hier aan WEL een hele goede bijdrage kunnen leveren.  Zo ook Rens Verhage, die een aantal goede en scherpe validaties heeft uitgevoerd. En waarbij overigens “het model van Topicus” dat hierboven als “afwijkend” wordt geframed totaal irrelevant is.

We moeten naar een model waarbij het schema en de code die het schema gebruikt wordt gepubliceerd als open source. KING heeft een rol als eigenaar van het schema, maar iedere leverancier kan als contributer het schema uitbreiden en het bijbehorende evidence (code) aanleveren die bewijst dat de uitbreiding aan de doelstellingen voor standaardisatie voldoet. Vervolgens kan de contributer vragen of KING het opneemt in het “master schema” zodat het kan worden gedeeld met andere contributers. Als de aanpassingen in het schema goed zijn en de codegeneratie werkt, de bijdrage past in het pattern en in de businessvraag voor dit specifieke koppelvlak, dan kan KING het opnemen en delen. De combinatie van code repository, pull requests, wiki en issue tracker zoals Github dat biedt, ondersteunt dit proces op een professionele manier.

Zo kun je bijvoorbeeld via Github vragen aan contributers een bijdrage te leveren voor:

Nieuwe operatie
Nieuwe gemeenschappelijk types introduceren
Nieuwe entiteit introduceren
Nieuwe kenmerken toevoegen

Met een goede versioneringsstrategie kan zoveel mogelijk worden geborgd dat het oude niet breekt. In tegenstelling wat hierboven wordt gesteld, hoeft “het snel versies van standaarden maken” helemaal geen ongunstige ontwikkeling te zijn voor de interoperabiliteit. Sterker nog, voor gemeenten is het een zege. Draaide het niet allemaal om de invulling van hun businessvragen?

Rens Verhage

We moeten naar een model waarbij het schema en de code die het schema gebruikt wordt gepubliceerd als open source. KING heeft een rol als eigenaar van het schema, maar iedere leverancier kan als contributer het schema uitbreiden en het bijbehorende evidence (code) aanleveren die bewijst dat de uitbreiding aan de doelstellingen voor standaardisatie voldoet. Vervolgens kan de contributer vragen of KING het opneemt in het “master schema” zodat het kan worden gedeeld met andere contributers. Als de aanpassingen in het schema goed zijn en de codegeneratie werkt, de bijdrage past in het pattern en in de businessvraag voor dit specifieke koppelvlak, dan kan KING het opnemen en delen. De combinatie van code repository, pull requests, wiki en issue tracker zoals Github dat biedt, ondersteunt dit proces op een professionele manier.

Dit is de transparantie waar ik deels op doel. Ik zou graag zien dat we via een open platform samenwerken aan de standaarden waarmee de we de processen bij onze klanten moeten ondersteunen. Dat neemt overigens niet weg dat KING haar rol als kwaliteitsbewaker verliest, in tegendeel, als eigenaar van de repository bepaalt KING uiteindelijk wat er allemaal wel of niet in de standaard komt. De rol van KING verschuift hierin wel enigszins, de duale rol van kwaliteitsbewaker en ontwikkelaar wordt meer die van kwaliteitsbewaker, wat het mijns inziens behoort te zijn.

Volgens mij zijn gemeenten zeer gebaat bij standaarden die ontwikkeld worden door de leveranciers van de applicaties die hun processen moeten ondersteunen. Leveranciers weten als geen ander waar een standaard in moet voorzien om processen sluitend te krijgen en kunnen daar ook actief in bijdragen.

En het is helemaal niet zo dat iedere leverancier op deze manier zijn eigen versie van de standaard gaat implementeren. Dat lijkt me ook helemaal niet handig, dan heb ik als leverancier een eigen StUF-dialect, maar ik kan met niemand praten omdat de rest het niet begrijpt. Buiten dat, zijn er nu geen eigen variaties / implementaties / interpretaties van standaarden? We hopen het niet, in de praktijk blijkt helaas vaker van wel. In ieder geval kunnen we het nu niet zien en dat is een stuk vervelender.

Joeri Bekker

Als een "nieuwkomer" die heeft gewerkt aan een implementatie van de ZDS 1.2 specificatie, kunnen wij ons zeker vinden in de meeste suggesties die hier worden gedaan. Sleutelwoorden zijn: 1) meer samenhang, 2) meer transparantie, 3) modernere aanpak en standaarden.

Github is geen doel op zich maar een middel om deze 3 zaken te bereiken zoals Cathy en Rens al aangeven. Het biedt in mijn ogen ook tal van praktische voordelen met zich mee: Wijzigingen in schema's zijn in één keer duidelijk en exact. De reden van de wijzigingen daarmee ook. Het refereren naar schema delen voor discussie volstaat met een link of inline in het schema op Github, in plaats van lappen specificatie te quoten op het forum. Het maakt discussie over (voorgestelde) wijzigingen makkelijker en aantoonbaar met testcode.

Eelco refereert naar een continuous integration (CI) en continuous deployment (CD) omgeving. Hoewel dat helemaal aansluit bij hoe wij werken, zou ik voor KING zeggen: Begin met het geautomatiseerd testen van de schema's met bijv. Travis-CI. Kunnen ze ingeladen worden door de meest gebruikte frameworks? De RSGB Bevragingen waar Cathy naar refereert om claims met testcode te valideren om de kwaliteit te behouden past hier ook in, en ik kan me er helemaal in vinden.

Een stap verder zou een (minimale headless) referentie implementatie zijn, zodat ook gekeken kan worden naar praktische issues en welke er zaken breken in de referentie implementatie bij een schema update. Aannames die bij zo'n referentie implementatie gemaakt worden kunnen worden ingezien door alle leveranciers. Deze aannames ontbreken vaak in de documentatie maar worden met zo'n referentie implementatie direct duidelijk.

Een CI omgeving waar een referentie implementatie tegen de nieuwe schema's wordt aangehouden zou een hoop frustratie schelen. Zo'n referentie implementatie kan dan ook gebruikt worden om het StUF testplatform te testen, want dat laat echt te wensen over.

Frank Samwel

Uit de discussie lijkt het nu net alsof KING tegen de hier voorgestelde aanpak is. Dat is denk ik niet zo. 

We zitten midden in een vernieuwing van de standaarden, waarbij niet de techniek maar het paradigma achter de standaarden naar mijn mening de grootste verandering is. Daarbij hoort ook een andere manier om standaarden te ontwikkelen en beheren, waarvoor we bij het ontwikkelen van RSGB bevragingen hebben laten zien hoe het ook kan. Ik kan me goed voorstellen dat het gebruik van Github een voor de hand liggende keuze is om dit proces te ondersteunen.

Op dit moment hebben we ook een aantal StUF standaarden die we beheren. Deze standaard en ook het beheermodel daaromheen is in de loop van jaren uitontwikkeld. We vinden daar van alles van, daarom zijn we ook de vernieuwing begonnen, maar het lijkt me nu niet handig om ook het beheermodel voor StUF standaarden volledig om te gooien. Deze standaarden zijn het resultaat van uitgebreid bespreken, afwegen en compromissen sluiten, en daarbij geven belanghebbenden in de werkgroepen duidelijk aan weinig interessere hebben in het versnellen van de versie-frequentie voor de standaarden. Michiel wijst hier al op in zijn reactie.

Vanuit KING willen we nu liever meer energie steken in de vernieuwingsbeweging, en dus de StUF standaard of het beheermodel voor de StUF standaard, niet heel ingrijpend meer veranderen. En dus juist wel werken aan een nieuwe manier om de standaarden in de vernieuwing op een modernere, snellere en interactievere manier te ontwikkelen en beheren.

Ik zou graag met jullie in gesprek gaan om het voorstel dat hier gedaan wordt voor het anders beheren van de standaarden uit te werken.

Εelcο Ηοtting

Zullen we specifieke over dit onderwerp een sessie doen, met als doel aan het einde een heel concreet beeld te hebben hoe we de standaarden in de toekomst "developer friendly" kunnen beheren, inclusief afspraken over tooling?

Ik merk dat er nu veel initiatieven zijn, die vanaf buiten gezien niet allemaal op elkaar lijken aan te sluiten. 

Bijv. de Open Raads Informatie API op Swaggerhub, OAS3. Voornemen om RESTful API's voor RSGB te maken met Amsterdam, op GitHub - en ook nog wat voorzichtige verkenningen rond ZDS 2.0. 

Een sessie waarbij degenen die aan het werk gaan "met API's" even afstemmen zodat het allemaal op dezelfde manier gaat lijkt me nuttig.