VERA Release en versiebeleid

VERA Standaard > Standaarden > Release en versiebeleid

Wijzigingen

Iedere vrijdag komt het VERA architectuurteam bij elkaar om wijzigingen door te voeren op de standaard. Deze wijzigingen komen voort uit:

  • RFC's vanuit leveranciers.
  • Projecten om grote uitbreidingen voor te bereiden.
  • Werkgroepen die bepaalde thema's uitwerken.
  • Feedback vanuit de praktijk


RFC's en andere vragen kunnen naar architectuur@stichting-vera.nl

Referentiedata

Een uitbreiding van referentiedata heeft geen impact op de technische API's. Daarom worden nieuwe waarden voor de referentiedata direct gepubliceerd. Wanneer bestaande referentiedata-waarden niet meer van toepassing zijn worden deze obsolete verklaard. Dat wil zeggen dat de waarden nog beschikbaar blijven tot de volgende MAJOR-versie. Referentiedata-waarden die in VERA 4.0 obsolete verklaard zijn kunnen gebruikt blijven in alle patches en minor-releases van VERA 4.0. Vanaf VERA 5.0 zullen deze waarden niet meer beschikbaar zijn. Er is geen harde link tussen referentiedata en bepaalde API versies. De referentiedata wordt in Excel formaat gepubliceerd en krijgt per nieuwe versie de publicatiedatum in de naam. Bijv. VERA - Referentiedata - 2022-02-18.xlsx

Wiki

Wijzigingen in de modellen en documentatie op de wiki worden per Major en Minor versie gepubliceerd. Er is een redactieomgeving van de wiki waarop de Pre-release staat van de volgende Major of Minor versie. Deze bevat alle wijzigingen tot dusver en zal tot aan de release continue wijzigen.

Semantic Versioning

API's

We sluiten net als OpenApi aan bij Semantic Versioning 2.0.0 https://semver.org/

Gegeven een versienummer in de vorm

MAJOR.MINOR.PATCH-<PRE-RELEASE>+<BUILD>

worden de individuele elementen als volgt verhoogd:

  • MAJOR wordt verhoogd bij incompatibele API-wijzigingen,
  • MINOR wordt verhoogd bij het toevoegen van functionaliteit die compatibel is met de vorige versie,
  • PATCH wordt verhoogd bij bugfixes.


Er zijn aanvullende labels beschikbaar voor pre-release en build-metadata om toe te voegen aan het MAJEUR.MINEUR.PATCH-formaat.

  • PRE-RELEASE wordt toegepast bij het toevoegen van functionaliteit voor de volgende minor of major versie.
  • BUILD wordt verhoogd bij iedere wijziging op de ontwikkelstraat.


Compatibiliteit

  • Technische compatibiliteit

Alle sub-versies zijn technisch compatible met een Major versie. De major versie is onderdeel van de url. Bijv. : /v4

  • functionele compatibiliteit

Zowel Major, Minor, Patch en Pre-releases kunnen uitbreidingen op functionaliteit hebben. Vaak is het nodig om dan dezelfde versie te gebruiken. Zolang je deze nieuwe functionaliteit niet ondersteunt dan is het niet nodig om een nieuwe versie te implementeren. Je blijft dus altijd compatible binnen de Major versie ongeacht welke subversie je in gebruik hebt.

  • Obsolete verklaring

Wanneer in de doorontwikkeling van VERA wordt geconstateerd dat onderdelen van het VERA-model niet meer van toepassing zijn worden deze obsolete verklaard. Deze onderdelen blijven dan nog beschikbaar in alle MINOR- en PATCH-versies maar worden verwijderd uit de eerstvolgende MAJOR-versie. Wanneer bijvoorbeeld in VERA 4.0 een attribuut uit een klasse obsolete wordt verklaard zal dit nog geen gevolgen hebben voor de technische API's van versie 4.x. In de API's van VERA 5.x zal dit attribuut niet meer beschikbaar zijn.

Definities

Non Breaking Changes

Non breaking changes mogen in minor of patch.

  • Nieuwe attributen, resources, responses en metadata
  • Wijziging documentatie
  • Toevoegen security schemes, filters en parameters
  • Toevoegen informatiedomein, Entiteiten, Ketenprocessen en Berichten

Breaking changes

Mogen alleen in een major of bugfix.

  • Hernoemen attributen, resources, responses, metadata, security schemes, filters, parameters
  • Wijziging type van attribuut
  • Verwijderen attributen, resources, responses, metadata
  • Verwijderen security schemes, filters, parameters
  • Hernoemen/verwijderen informatiedomein, Entiteiten, Ketenprocessen en Berichten
  • Verplaatsen Entiteiten en Berichten naar andere domeinen.

Bugfix

Soms worden er fouten gemaakt bij de realisatie van de standaard. Deze kunnen zowel technisch als functioneel zijn. Een bugfix is een reparatie op technisch of functioneel niveau. Een kritieke fout die snel opgelost moet worden. Dit kan leiden tot een breaking change met de voorgaande release. De aangepast versie met de bugfix vervangt dan de voorgaande versie.

Build

Een build is de laatse versie van de API's op de ontwikkelstraat. Deze kunnen zowel breaking als non-breaking changes bevatten. Alle door het architectuurteam doorgevoerde wijzigingen zijn daar direct direct zichtbaar. Handmatig kunnen er ook builds gemaakt worden van andere versies. Een build kan worden opgenoman als Patch OF in de Pre-Release.

Pre-release

Een pre-release is de versie waarin waar non-breaking changes zijn verwerkt die onderdeel worden van de volgende minor of major versie. Je kunt deze al gebruiken als daar functionaliteit inzit die je nodig hebt. Maar het is en blijft een pre-release en kan fouten bevatten dus gebruik is op eigen risico.



VERA&CORA logo.png