Lint workflow voor alle repo's

[CathyDingemanse]

Lint workflows voor alle repo's in orde te maken.

[MelvLee]

de volgende statements moeten worden uitgevoerd in de parent map van een specificatie map:

• npm init -y. Dit creert en initialiseert een package.json bestand in de parent map
• npm install --save-dev @openapitools/openapi-generator-cli. (code generatie tool)
• npm install --save-dev @stoplight/spectral. (linter)
• npm install --save-dev husky. (om pre-commit scripts uit te voeren)
• npm install --save-dev mvn-dl. (om packages uit maven repo's te downloaden)
• npm install --save-dev openapi-to-postmanv2. (postman collecties generator)

in package.json, onder scripts de volgende regels toevoegen:

"oas:generate-client": "openapi-generator-cli generate -i ./specificatie/genereervariant/openapi.yaml --global-property=modelTests=false,apiTests=false,modelDocs=false,apiDocs=false",
"oas:generate-java-client": "npm run oas:generate-client -- -o ./code/java -g java --additional-properties=dateLibrary=java8,java8=true,optionalProjectFile=false,optionalAssemblyInfo=false",
"oas:generate-netcore-client": "npm run oas:generate-client -- -o ./code/netcore -g csharp-netcore --additional-properties=optionalProjectFile=false,optionalAssemblyInfo=false",
"oas:generate-net-client": "npm run oas:generate-client -- -o ./code/net -g csharp --additional-properties=optionalProjectFile=false,optionalAssemblyInfo=false",
"oas:generate-python-client": "npm run oas:generate-client -- -o ./code/python -g python --additional-properties=optionalProjectFile=false,optionalAssemblyInfo=false",
"oas:generate-postman-collection": "openapi2postmanv2 -s ./specificatie/genereervariant/openapi.yaml -o ./test/BRP-Bevragen-postman-collection.json --pretty",
"oas:lint": "spectral lint ./specificatie/openapi.yaml",
"oas:lint-genereervariant": "spectral lint ./specificatie/genereervariant/openapi.yaml",
"preoas:resolve": "mvn-dl io.swagger.codegen.v3:swagger-codegen-cli:3.0.19 -f swagger-codegen-cli.jar",
"oas:resolve": "java -jar swagger-codegen-cli.jar generate -i ./specificatie/openapi.yaml -l openapi-yaml -o ./specificatie/genereervariant && java -jar swagger-codegen-cli.jar generate -i ./specificatie/openapi.yaml -l openapi -o ./specificatie/genereervariant",
"postoas:resolve": "rm swagger-codegen-cli.jar",

Pas de naam aan van de postman-collection.json bestand in de oas:generate-postman-collection script

de bovengenoemde scripts kunnen worden uitgevoerd met de volgende statement:

npm run <scriptnaam>, bijv. npm run oas:lint

in package.json, achter de één na laatste } de volgende regels toevoegen. Dit zorgt ervoor dat de openapi.yaml en de genereervariant tijdens een commit worden ge-lint:

,
  "husky": {
    "hooks": {
      "pre-commit": "npm run oas:lint && npm run oas:resolve && npm run oas:lint-genereervariant"
    }
  }

Om de Haal Centraal openapi rules te gebruiken, moet een .spectral.yml bestand worden aangemaakt met de onderstaande regels:

extends:
- https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-common/master/.spectral.yml
rules:
  oas3-valid-oas-parameter-example: off
  oas3-valid-oas-content-example: off

Om het genereren van de resolved variant, het linten, codegeneratie en postman collectie moeten de yml bestanden onder .github/workflows folder van bijv. de BRP-bevragen repo naar de parent map.

Pas in de generate-postman-collectie.yml bestand de naam van de postman-collection.json bestand aan. De naam moet overeenkomen met naam die wordt gebruikt in de oas:generate-postman-collection script

[melsk-r]

Deze action voor de genereerversie moet niet uitgerold worden op de BAG repo.

In principe voorziet deze action zodra uitgerold op andere repo's de gerelateerde GitHub Pages van de gewenste indicatoren alleen moet daarvoor wel in de 'index.md' de volgende statements opgenomen worden:

![lint oas](https://github.com/VNG-Realisatie/repo-naam/workflows/lint-oas/badge.svg)
![generate sdks](https://github.com/VNG-Realisatie/repo-naam/workflows/generate-sdks/badge.svg)
![generate postman collection](https://github.com/VNG-Realisatie/repo-naam/workflows/generate-postman-collection/badge.svg)

[melsk-r]

@MelvLee, Ik begrijp de volgende zin in jou post niet.

Om het genereren van de resolved variant, het linten, codegeneratie en postman collectie moeten de yml bestanden onder .github/workflows folder van bijv. de BRP-bevragen repo naar de parent map.

Zeg je hier eigenlijk dat de yaml bestanden in de .github/workflows folder verplaatst moeten worden naar de root?

Omdat dit issue al van november vorig jaar is en er op dit gebied stiekem al heel veel gedaan is en er ook wat zaken gewijzigd zijn heb ik alle repo's eens tegen dit issue aan gehouden. Ik wil voorkomen dat we wijzigingen gaan aanbrengen die misschien helemaal niet (meer) nodig of gewenst zijn. Hieronder dus per repo mijn vragen/opmerkingen.

BRK-bevragen

• .spectral.yml bevat niet de regel 'oas3-valid-oas-parameter-example: off'. Is het nog steeds de bedoeling die op te nemen of is de reden daartoe al komen te vervallen?
• in het package.json bestand zijn ook nog de hieronder staande regels toegevoegd. Wat is daarvan de functie en moeten deze ook bij de andere repo's aan het package.json bestand worden toegevoegd?

"unstage-generated": "git reset HEAD ./specificatie/genereervariant/openapi.* ./test/BRK-Bevragen-postman-collection.json ./code/",
"rollback-generated": "git checkout ./specificatie/genereervariant/openapi.* ./test/BRK-Bevragen-postman-collection.json ./code/",
"test": "echo "Error: no test specified" && exit 1"

Kadsterpersonen-bevragen

• docs/index.md bevat nog niet de indicatoren die README.md wel heeft. Kan ik aannemen dat we die nog toe moeten voegen?
• .spectral.yml bevat naast de hierboven gedefinieerde regels ook nog 'no-$ref-siblings: off' wat is daarvan de functie en moet die bij de andere repo's niet ook erin komen?

BRK-event-sourcing

• package.json bevat niet alle regels die Melvin in zijn post hierboven voorschrijft. Is dat bewust. Wellicht worden ze hier nog niet gebruikt maar is het niet handig om dit bestand overal hetzelfde te houden ongeacht of ze (al) wel of niet gebruikt worden?
• Er is nog geen .spectral.yml waarom niet?
• Waarom worden er in deze repo nog geen sdk's gegenereerd?
• Als we ook SDK's gaan genereren de indicator daarvoor toevoegen aan README.md en docs/index.md.

BRK-historie-bevragen

• Deze repo mist sowieso nog het meeste van de met dit issue gerelateerde content. Ik neem aan dat die content wel aangebracht moet worden?

BRK-WKPB

• in het package.json bestand is ook nog de hieronder staande regels toegevoegd. Wat is daarvan de functie?

"test": "echo "Error: no test specified" && exit 1"

• .spectral.yml bevat naast de hierboven gedefinieerde regels ook nog 'no-$ref-siblings: off' wat is daarvan de functie en moet die bij de andere repo's niet ook erin komen?
• README.md bevat nog niet de indicatoren terwijl het wel de 3 gerelateerde actions heeft.

BRP-bevragen

• in het package.json bestand is ook nog de hieronder staande regels toegevoegd. Wat is daarvan de functie?

"test": "echo "Error: no test specified" && exit 1"

Reisdocumenten-bevragen

• in het package.json bestand is ook nog de hieronder staande regels toegevoegd. Wat is daarvan de functie?

"test": "echo "Error: no test specified" && exit 1"

• Ik zie dat dit bestand ook op andere punten afwijkt van ditzelfde bestand in andere repo's. Zo wijken de property waarden van de properties van 'devDependencies' af. Zou dit bestand in de basis niet eigenlijk overal gelijk moeten zijn (op evt. vermeldde bestandsnamen na dan)?
• In dat bestand zie ik ook het hier onderstaande fragment. Klopt de waarde van de property 'url' wel?

"repository": {
"type": "git",
"url": "git+https://github.com/VNG-Realisatie/Haal-Centraal-BRP-bevragen.git"
},

Als dit niet correct is dan is dat mogelijk ook voor andere repo's niet correct.

BRP-tabellen-bevragen

• Deze repo mist sowieso nog het meeste van de met dit issue gerelateerde content. Ik neem aan dat die content wel aangebracht moet worden?

BRP-bewoning

• in het package.json bestand is ook nog de hieronder staande regels toegevoegd. Wat is daarvan de functie?

"test": "echo "Error: no test specified" && exit 1"

• Er is nog geen .spectral.yml waarom niet?

BRP-Update-API

• in het package.json bestand is ook nog de hieronder staande regels toegevoegd. Wat is daarvan de functie?

"test": "echo "Error: no test specified" && exit 1"

BRP-historie-bevragen

• in het package.json bestand is ook nog de hieronder staande regels toegevoegd. Wat is daarvan de functie?

"test": "echo "Error: no test specified" && exit 1"

• .spectral.yml bevat niet de in de post van Melvin genoemde regels. Is het nog steeds de bedoeling die op te nemen of is de reden daartoe al komen te vervallen?

BAG-bevragen

• Deze repo mist sowieso nog de met dit issue gerelateerde content. Moeten we dus nog in voorzien.

HR-bevragen

• Deze repo mist sowieso nog de met dit issue gerelateerde content. Ik neem aan dat die content wel aangebracht moet worden?

WOZ-bevragen

• in het package.json bestand is ook nog de hieronder staande regels toegevoegd. Wat is daarvan de functie?

"test": "echo "Error: no test specified" && exit 1"

• README.md en docs/index.md bevat nog niet de indicatoren terwijl het wel de 3 gerelateerde actions heeft.

BGT-bevragen

• Deze repo mist sowieso nog de met dit issue gerelateerde content. Hoewel het nog geen specificaties bevat zouden we daar deels al wel in kunnen voorzien.

Web-Security

• Deze repo zal geen yaml specs bevatten en genoemde voorzieningen zijn hier denk ik niet nodig.

[MelvLee]

@MelvLee, Ik begrijp de volgende zin in jou post niet.

Om het genereren van de resolved variant, het linten, codegeneratie en postman collectie moeten de yml bestanden onder .github/workflows folder van bijv. de BRP-bevragen repo naar de parent map.

Zeg je hier eigenlijk dat de yaml bestanden in de .github/workflows folder verplaatst moeten worden naar de root?

Wat ik hiermee wil zeggen is dat je de .github/workflows folder + inhoud moet copieren naar de root van de repo waar je deze workflows ook wil draaien

[MelvLee]

BRK-bevragen

• .spectral.yml bevat niet de regel 'oas3-valid-oas-parameter-example: off'. Is het nog steeds de bedoeling die op te nemen of is de reden daartoe al komen te vervallen?

De oas3-valid-oas-parameter-example rule is toegevoegd bij de BRP bevragen repo omdat we daar een array example als een komma separated string willen definieren. Dit is per definitie niet correct. Om de validatie toch niet te laten falen, is die rule daarom uitgezet. Bij repo's waar wij niet bewust een fout willen overrulen is deze rule ook niet uitgezet. Ik denk dat het goed is om te kijken of de rules die we in een .spectral.yaml file hebben uitgezet, nog steeds uitgezet moeten worden en of het niet beter is om de fout te fixen. Het uitzetten van een rule geldt namelijk voor de hele repo en niet alleen voor een specifiek geval

[MelvLee]

BRK-bevragen

• in het package.json bestand zijn ook nog de hieronder staande regels toegevoegd. Wat is daarvan de functie en moeten deze ook bij de andere repo's aan het package.json bestand worden toegevoegd?

"unstage-generated": "git reset HEAD ./specificatie/genereervariant/openapi.* ./test/BRK-Bevragen-postman-collection.json ./code/",
"rollback-generated": "git checkout ./specificatie/genereervariant/openapi.* ./test/BRK-Bevragen-postman-collection.json ./code/",
"test": "echo "Error: no test specified" && exit 1"

De twee scripts zijn bedoeld om de bestanden die mbv GitHub Actions worden gegenereerd niet te commit-en (unstage) en terug te draaien (rollback). De unstage-generated wordt gebruikt in de pre-commit hook. Dit zorgt er dus voor dat de gegenereerde bestanden niet worden ge-commit omdat het in GitHub ook gebeurd.
De rollback-generated script is meer voor gemak. Dan hoeft je niet één voor één de gegenereerde bestanden te rollback-en

[melsk-r]

Wat ik hiermee wil zeggen is dat je de .github/workflows folder + inhoud moet copieren naar de root van de repo waar je deze workflows ook wil draaien

@MelvLee Duidelijk nu. Waarbij natuurlijk wel geldt dat je alleen die actions meekopieert die ook van toepassing zijn voor de betreffende repo. De action 'lint-oas' is immers n.v.t. voor een repo waar geen 'openapi.yaml' aanwezig is.

De twee scripts zijn bedoeld om de bestanden die mbv GitHub Actions worden gegenereerd niet te commit-en (unstage) en terug te draaien (rollback). De unstage-generated wordt gebruikt in de pre-commit hook. Dit zorgt er dus voor dat de gegenereerde bestanden niet worden ge-commit omdat het in GitHub ook gebeurd.
De rollback-generated script is meer voor gemak. Dan hoeft je niet één voor één de gegenereerde bestanden te rollback-en

@MelvLee Ik begrijp het denk ik nog niet helemaal dus hieronder even mijn interpretatie. Graag hoor ik van je waar ik er naast zit. Als ik het goed begrijp kan ik de beschrijving in de API Kennisbank nl. aanpassen.

Volgens mij hebben deze scripts vooral een functie in een lokale versie van een repo (bijv. als je met GitHub Desktop werkt).
Het kan zijn dat je om de eoa reden daar de actions uitvoert. Bijv. om te testen of ze goed functioneren. De bestanden die daarmee gegenereerd wordt wil je echter niet committen. Het is immers de taak van de actions in de upstream repo om er voor zorgen dat deze bestanden op gezette tijden gegenereerd worden.
De scripts die jij hierboven beschrijft zijn er dus voor om:

1. de gegenereerde bestanden te 'unstagen'. Ze worden dus niet meegenomen in een evt. commit.
2. er voor te zorgen dat de bestanden lokaal ge'-'rollbacked' worden. Volgens mij betekent dat eigenlijk dat ze verwijderd worden.

Blijven er nog enkele vragen over:

1. Waartoe dient de regel '"test": "echo "Error: no test specified" && exit 1"'
2. Wat moet je doen om deze scripts uit te voeren? Door 'npm run unstage-generated' en 'npm run rollback-generated' uit te voeren?
3. Het lijkt er op dat dit script alleen werkt voor het bestand 'BRK-Bevragen-postman-collection.json', dus alleen voor de bestanden die je genereert met de acton 'generate-postman-collection'. Hoe zit dat dan voor de bestanden die je genereert met de actions 'generate-sdks', 'lint-oas' en 'generate-user-stories-md'? Is het daarvoor niet nodig de bestanden te 'unstagen' en te 'rollbacken'?
   Ook zou ik alle '.spectral.yml' bestanden gelijk aan elkaar willen maken. De vraag is alleen of daaraan in alle repo's de regel 'no-$ref-siblings: off' mag worden toegevoegd.

[MelvLee]

Waartoe dient de regel '"test": "echo "Error: no test specified" && exit 1"'

Als je in je repo testen hebt, dan zou je die aan deze script kunnen toevoegen. De repo's hebben op dit moment geen testcode, dus kan deze script weg

Wat moet je doen om deze scripts uit te voeren? Door 'npm run unstage-generated' en 'npm run rollback-generated' uit te voeren?

Dat klopt

Het lijkt er op dat dit script alleen werkt voor het bestand 'BRK-Bevragen-postman-collection.json', dus alleen voor de bestanden die je genereert met de acton 'generate-postman-collection'. Hoe zit dat dan voor de bestanden die je genereert met de actions 'generate-sdks', 'lint-oas' en 'generate-user-stories-md'? Is het daarvoor niet nodig de bestanden te 'unstagen' en te 'rollbacken'?

De scripts unstage en rollback alle bestanden die lokaal worden gegenereerd.

git reset HEAD ./specificatie/genereervariant/openapi.* ./test/BRK-Bevragen-postman-collection.json ./code/ is gelijk aan

git reset HEAD ./specificatie/genereervariant/openapi.*
git reset HEAD ./test/BRK-Bevragen-postman-collection.json
git reset HEAD ./code/

Je kan meerdere paden opgeven

Ook zou ik alle '.spectral.yml' bestanden gelijk aan elkaar willen maken. De vraag is alleen of daaraan in alle repo's de regel 'no-$ref-siblings: off' mag worden toegevoegd.

Vanaf OAS 3.1 is dit niet meer relevant. Dan mag $ref wel siblings hebben. Je kan nu ervoor kiezen om de 'no-$ref-siblings: off' rule te verwijderen uit de .spectral.yml van alle repo's en de rule alleen toe te voegen in de .spectral.yml van Haal Centraal Common. Dit kan je dus ook doen als je een rule uit wil zetten voor alle HC repo's

[melsk-r]

@MelvLee Voor de meeste repositories is de lint workflow inmiddels correct geïmplementeerd.
In de repository voor de HR API speelt echter een klein probleempje. We werken in deze repo volgens de GitFlow methode.
Aangezien er voor de openapi specificaties in deze repo nog geen officiële versie is uitgebracht zijn deze alleen beschikbaar in de 'develop' branch en nog niet in de 'master' (of 'main') branch.
De actions die de postmanscripts en de sdk's opleveren gaan daar echter wel vanuit met als gevolg dat in de GitHub Pages site voor deze API een rode badge wordt getoond voor deze actions.

De GitFlow uitgangspunten lijken dus wat te conflicteren met deze actions. Vreemd is echter wel dat de action 'lint-oas' wel een genereervariant oplevert in de 'develop' branch.
Dit schrijvende realiseerde ik me echter dat de badges in het README bestand en in de docs/index.md mogelijk helemaal niet de juiste status weergeven.

Laten we, om het eenvouidg te houden, even uitgaan van een repository die geen gebruik maakt van GitFlow.

De 'master' of 'main' branch bevat dan altijd de laatste status van de openapi specs.

• Is er nog geen officiële versie gepubliceerd dan is dat tevens de enige status en de actions kunnen dan ook alleen op deze branch acteren. De badges in het README bestand en in de docs/index.md tonen dan ook altijd de juiste status.
• Is er al wel een officiële versie dan staat deze in een tag en bevat de 'master' of 'main' branch wellicht al een beta van de volgende versie. De actions werken echter nog steeds op deze 'master' of 'main' branch met als gevolg dat de badges in de README maar vervelender in de docs/index.md de status van de beta versie tonen. Ik kan me voorstellen dat je dat voor de README prima vindt maar in de GitHub Pages pagina wil je n.m.m. toch eigenlijk wel de status van de versie in de laatste tag tonen.

Lijkt me goed om hier nog eens goed naar te kijken.
Dat het met een repository die met GitFlow werkt nog wat ingewikkelder ligt moge duidelijk zijn.

[MelvLee]

De actions die de postmanscripts en de sdk's opleveren gaan daar echter wel vanuit met als gevolg dat in de GitHub Pages site > voor deze API een rode badge wordt getoond voor deze actions.

Je zou de npm script kunnen aanpassen dat hij alleen wordt uitgevoerd als er een genereervariant is. Nadeel hiervan is dat je wel een groene badge krijgt en dan denk je dat er sdks of een postman collection is, maar die is er niet. Persoonlijk zou ik ervoor kiezen om in dat geval nog geen github actions toe te voegen voor het genereren van de sdks en postman collection. Consumers kunnen toch nog niks met de sdks en postman collection omdat er nog geen api is om tegen aan te testen.

De GitFlow uitgangspunten lijken dus wat te conflicteren met deze actions. Vreemd is echter wel dat de action 'lint-oas' wel >een genereervariant oplevert in de 'develop' branch.

De 'lint-oas' action en de ook de andere actions werken voor alle branches. Dit is in de action geconfigureerd.

Default toont de badge de laatste status van de bijbehorende action die is gedraaid op de master. Wil je dat niet, dan kan je dat aanpassen door de 'branch' query parameter te gebruiken. Voorbeeld:

Nadeel hiervan is dat de readme.md voor elke branch anders is/moet zijn. Je moet dus elke keer als je gaat mergen de conflict in de readme.md resolven.

• Is er nog geen officiële versie gepubliceerd dan is dat tevens de enige status en de actions kunnen dan ook alleen op deze > branch acteren. De badges in het README bestand en in de docs/index.md tonen dan ook altijd de juiste status.
• AIs er al wel een officiële versie dan staat deze in een tag en bevat de 'master' of 'main' branch wellicht al een beta van de > volgende versie. De actions werken echter nog steeds op deze 'master' of 'main' branch met als gevolg dat de badges in de > README maar vervelender in de docs/index.md de status van de beta versie tonen. Ik kan me voorstellen dat je dat voor de > README prima vindt maar in de GitHub Pages pagina wil je n.m.m. toch eigenlijk wel de status van de versie in de laatste tag tonen.

Je kan de branch query parameter gebruiken om dit te sturen. Je kan er ook voor kiezen om alleen de badges te tonen voor delen dat een consumer al kan gebruiken.

Ik denk dat dit niet te maken heeft met het gebruiken van GitFlow. GitFlow beschrijft alleen maar een gestandaardiseerde manier om met branches in een development lifecycle te werken. Dit probleem heb je zodra je met branches werkt. Het kan worden opgevangen door het gebruik van de branch query parameter. Nadeel hiervan is dan wel weer dat je altijd een merge conflict krijgt in de readme.md bestanden die je handmatig moet resolven. Of je kiest voor één branch en met forks werken, maar dan heb je weer andere problemen.

[melsk-r]

Je zou de npm script kunnen aanpassen dat hij alleen wordt uitgevoerd als er een genereervariant is. Nadeel hiervan is dat je wel een groene badge krijgt en dan denk je dat er sdks of een postman collection is, maar die is er niet.

Ok, ik neem aan dat je bedoelt dat er standaard altijd een groene badge is voor de sdks en postman collection ook al zijn deze er nog niet. Lijkt me inderdaad niet de way to go.

Persoonlijk zou ik ervoor kiezen om in dat geval nog geen github actions toe te voegen voor het genereren van de sdks en postman collection. Consumers kunnen toch nog niks met de sdks en postman collection omdat er nog geen api is om tegen aan te testen.

Daar kan ik me wel in vinden. Zolang er nog geen (referentie) implementatie is dus geen badges voor sdks en postman collection maar wel voor de oas linter. Ik zie alleen nog wel een bron van onduidelijkheid. Neem bijv. de GitHub page voor de BRK Bevragen API waar de badges in de main pagina staan. De vraag is of het iedereen wel duidelijk is dat deze slaan op de 1.2 (Live) versie of zou men ook kunnen denken dat deze (ook) op de 1.3 (IO) versie betrekking hebben?
In dat laatste geval moeten we daar explicieter over zijn.

Ik denk dat dit niet te maken heeft met het gebruiken van GitFlow. GitFlow beschrijft alleen maar een gestandaardiseerde manier om met branches in een development lifecycle te werken. Dit probleem heb je zodra je met branches werkt.

Ik ben het eigenlijk wel met je eens dat het meer te maken met het feit dat je gebruik maakt van branches.

Dat het met een repository die met GitFlow werkt nog wat ingewikkelder ligt moge duidelijk zijn.

Ik realiseer me nu dat het feit dat we GitFlow gebruiken het juist makkelijker maakt. De master/main branch bevat, zolang GitFlow netjes gevolgd wordt, immers altijd de laatste officiële versie van de API specificaties.