Release en versiebeleid
Wijzigingen[bewerken | brontekst bewerken]
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
Het VERA Architectuurteam is enorm blij met de toewijding van de VERA community en met alle gebruikers die kritisch meedenken over de standaard. Alle feedback in de vorm van verbetervoorstellen, maar ook over algemene issues die opgemerkt worden, is meer dan welkom. Mocht een issue of optimalisatie in beeld zijn, schroom niet om deze te delen met het Architectuurteam. Deze meldingen worden wekelijks bekeken en beoordeeld. Dit kan leiden tot een directe actie/verbetering als dat opportuun is, of tot een opdracht voor op de backlog.
Het delen van verbetervoorstellen, vragen of opmerkingen kan, naast een e-mail naar vera-architectuurteam@aedesdatastandaarden.nl, eenvoudig op deze locatie: https://github.com/Aedes-datastandaarden/vera-openapi/issues
Referentiedata[bewerken | brontekst bewerken]
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[bewerken | brontekst bewerken]
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.
API's[bewerken | brontekst bewerken]
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[bewerken | brontekst bewerken]
- 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[bewerken | brontekst bewerken]
Non Breaking Changes[bewerken | brontekst bewerken]
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[bewerken | brontekst bewerken]
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[bewerken | brontekst bewerken]
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[bewerken | brontekst bewerken]
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[bewerken | brontekst bewerken]
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.
