Ga naar hoofdinhoud

Versionering

Applicatie / Container / Helm chart​

Alle applicaties, containers en Helm charts volgen de "semantic versioning" regels, zoals deze beschreven staan op semver.org. Hierbij krijgen applicatie, container en Helm chart van een component, dezelfde versie. Hierdoor zijn deze dan ook eenvoudig aan elkaar te linken. Enige kleine uitzondering hierop is dat de golang applicaties een semantic versioning versie krijgen met een "v" prefix, zoals gangbaar is bij golang modules. De webservice API zal wel een versie krijgen welke los staat van eerder genoemde versie. Meer daarover: Webservice API

De versies worden opgehoogd bij elke nieuwe merge van een merge request (Gitlab CI) naar de master branch. Dit gebeurt automatisch door een stap in de Gitlab Pipeline welke de patch versie ophoogt. De minor en major versies worden handmatig opgehoogd zodra er sprake is van "new functionality" of "breaking changes".

De versie van de component zelf kan achterhaald worden door het volgende endpoint te raadplegen:

  • /api/version

De inhoud van elke versie van een component zal terug te vinden zijn in de release notes, onderverdeeld in de hoofdstukken "breaking changes", "new functionality" en "patches". Deze release notes worden bijgehouden bij elk component in een RELEASE_NOTES.md bestand in de root van de git repository van het project. Meer over release notes

De laatste stabiele versies van de componenten worden bijgehouden op Component Versies.

Webservice API​

Het project Vorderingenoverzicht Rijk volgt de NLGov REST API Design Rules voor de API-strategie van alle componenten. Onderdeel hiervan zijn de regels voor versioning. Hieronder wordt uitgelegd hoe we hier invulling aan geven.

Van de beschikbare API endpoints is een overzicht te vinden, door een van de OpenAPI Specification endpoints van het component te raadplegen:

  • /api/openapi.yaml
  • /api/openapi.json

Deprecation schedule​

Indien een component een deprecation schedule heeft, dan zal deze in een bestand genaamd API_DEPRECATION_SCHEDULE.md in de git repository van het betreffende component te vinden zijn. Is het bestand niet aanwezig, dan geldt er (nog) geen deprecation schedule. In het bestand is te vinden welke versie de actuele versie is, wat de verouderde versie is en per welke datum de verouderde versie niet meer ondersteund wordt.

Transition period​

Indien een nieuwe major versie van een API beschikbaar komt, dan zal deze naast de bestaande API-versie beschikbaar gesteld worden. Afnemers krijgen vervolgens 12 maanden de tijd om over te stappen op de nieuwe versie. Daarna zal de oude versie verwijderd worden en zodoende niet meer werken. Wanneer de 12 maanden eindigen, zal terug te vinden zijn in het deprecation schedule. Merk op dat er te aller tijden maximaal 2 versies ondersteund worden.

URI version​

Componenten met een webservice (REST) API, hebben de API ge-versioneerd door de major versie toe te voegen aan het "path". De versie van een API endpoint bestaat uit een "v", gevolgd door een enkel getal.
Dus bijvoorbeeld: /api/v2/some-endpoint

Changelog​

Alle wijzigingen aan de API van een component zijn terug te vinden in een bestand genaamd API_CHANGELOG.md welke te vinden is in de root van de git repository van de component.

Semantic versioning​

De API's worden geversioneerd volgens de regels van Semantic Versioning.

  • Bij "breaking changes" wordt de major versie opgehoogd
  • Bij "new functionality" wordt de minor versie opgehoogd
  • Bij "small fixes" wordt de patch versie opgehoogd

Er wordt gestreefd om de API-wijzigingen, zoveel mogelijk, backwards compatible te houden. Zodoende is er geen major update en zijn de afnemers van een API minder afhankelijk van elke verandering en worden daardoor niet gedwongen om te upgraden naar een nieuwe API-versie.
Om dit te kunnen bereiken:

  • zal het gedrag van een API niet moeten veranderen bij een wijziging
  • zullen velden in de data niet hernoemd of verwijderd moeten worden
  • zal het endpoint van de webservice niet moeten wijzigen

Alhoewel er naar backwards compatibility wordt gestreefd, zullen er situaties zijn waarbij dit niet op een goede manier te doen is. In dit geval zal de versie van de API opgehoogd worden en naast de oude geserveerd worden, gedurende een transition period. Daarnaast zal in de release notes van het component vermeld moeten worden dat er breaking API-wijzigingen zijn en dat er een nieuwe major API-versie beschikbaar is.

Version header​

De API's geven een API-Version HTTP response header terug, met als waarde de volledige versie. Dus bijvoorbeeld:

API-Version: 0.18.12

Financial claims information document (FCID)​

De beschikbare FCID-versies zijn hier terug te vinden: Financial claims information document

Release notes​

Er zijn twee soorten release notes beschikbaar:

  • technische release notes, bedoeld voor technische gebruikers die een component willen beheren of die een connectie met een component willen ontwikkelen
  • functionele release notes, bedoeld voor eindgebruikers van de web-/native applicatie (user_ui)

De technische release notes kunnen gevonden worden in een bestand genaamd RELEASE_NOTES.md, in de root van de git-repository van de component. Aangezien de technische release notes gericht zijn aan een technisch publiek, zullen deze, net zoals de code, in het Engels geschreven zijn.

De functionele release notes zijn in de web-/native app zelf terug te vinden. Aangezien de functionele release gericht zijn aan Nederlandse gebruikers, zullen deze in het Nederlands geschreven zijn.