From 2e5e82fa9d69e1d8358b25ebbe12f6b21a4c6b38 Mon Sep 17 00:00:00 2001 From: Edwin Wisze Date: Fri, 2 Sep 2022 11:32:35 +0200 Subject: [PATCH 01/30] Digikoppeling versie van bijlagen Overgekopieerd --- bijlage01_Respec.md | 2 +- bijlage02_GebruikGithub.md | 14 +++++++++----- bijlage03_Versienummering.md | 31 ++++++++++++++++++------------- 3 files changed, 28 insertions(+), 19 deletions(-) diff --git a/bijlage01_Respec.md b/bijlage01_Respec.md index 628beea..21464f7 100644 --- a/bijlage01_Respec.md +++ b/bijlage01_Respec.md @@ -1,7 +1,7 @@ # Bijlage: Gebruik ReSpec Voor publicatie van de standaarden die bij Logius en beheer zijn wordt gebruik gemaakt van ReSpec. ReSpec is een applicatie om technische -documentatie te maken die publiceerbaar is op het net en gemakkelijk +documentatie te maken die publiceerbaar is op het internet en gemakkelijk kan worden geïndexeerd door zoekmachines om de documentatie vindbaar te maken. Het is ontwikkeld ten behoeve van de documentatie van W3C standaarden. Door gebruik te maken van ReSpec publiceren we documentatie diff --git a/bijlage02_GebruikGithub.md b/bijlage02_GebruikGithub.md index 34bf7d6..5ccee29 100644 --- a/bijlage02_GebruikGithub.md +++ b/bijlage02_GebruikGithub.md @@ -5,12 +5,12 @@ GitHub biedt functionaliteit om documenten te publiceren vanuit een repository. Logius gebruikt deze functionaliteit om het met [ReSpec](#bijlage-gebruik-respec) gegenereerde document te publiceren als HTML-document en een PDF-document. Deze documenten worden automatisch -gekopieerd naar een publicatiewebsite onder Logiusbeheer. +gekopieerd naar een publicatiewebsite onder beheer van Logius. ## Wijzigingsvoorstellen Het proces zoals beschreven onder [operationeel beheer, wensen en eisen](#wensen-en-eisen) -wordt voor de Logius standarden geïmplementeerd door gebruik te maken +wordt voor de Logius standaarden geïmplementeerd door gebruik te maken van _GitHub issues_. Een _issue_ kan binnen GitHub ingediend worden door iedere (GitHub)gebruiker en wordt bij ontwikkeling van code gebruikt om functionele wensen of gevonden bugs in te dienen zodat @@ -25,8 +25,8 @@ van een document. De _develop_ branch bevat een werkversie met daarin alle wijzigingen die in een volgende geaccepteerde versie opgenomen moeten worden. -Aanpassingen in de documentatie die voor een specifiek wijzingsvoorstel -gemaakt worden worden in eigen branch verwerkt. Deze branch wordt gesplitst vanaf de _develop_ branch en wordt nadat het wijzigingsverzoek aangenomen +Aanpassingen in de documentatie die voor een specifiek wijzigingsvoorstel +gemaakt worden worden in een eigen branch verwerkt. Deze branch wordt gesplitst vanaf de _develop_ branch en wordt nadat het wijzigingsverzoek aangenomen is teruggebracht naar de _develop_ branch. Voorbeeld: een wijzigingsverzoek voor het aanpassen van de architectuurbeschrijving zal in een branche _nieuwe architectuur_ worden verwerkt. Deze wordt gesplitst vanaf, en teruggebracht naar, de _develop_ branch. Door wijzigingen in een eigenaarbranch op te nemen zijn alle wijzigingen op de documentatie inzichtelijk per wijzigingsvoorstel. @@ -49,7 +49,7 @@ issues als 2. **Scope** Vooral relevant voor wijzigingsvoorstellen. Hiermee wordt aangegeven of het een kleine of grote wijziging betreft. Dit heeft betrekking op de impact van een wijziging en daarmee op de - [versienummering](#bijlage-versie-nummering-digikoppeling-onderdelen). + [versienummering](#bijlage-versie-nummering-logius-standaarden). 1. Klein 2. Groot 3. **Overleg** Het label Overleg heeft alleen betrekking op wijzigingsvoorstellen. @@ -69,6 +69,10 @@ issues als 6. Gereed 7. Afgewezen +## Patches + +_TODO: beschrijving patching operationeel_ + ## Automatisering en scripts GitHub ondersteunt automatisering van taken door scripts. Standaard is de publicatie via _github pages_. Binnen de Logius standaarden maken diff --git a/bijlage03_Versienummering.md b/bijlage03_Versienummering.md index 758fc44..f1bebc1 100644 --- a/bijlage03_Versienummering.md +++ b/bijlage03_Versienummering.md @@ -1,6 +1,9 @@ # Bijlage: versie-nummering Logius standaarden Deze bijlage beschrijft de versioneringsmethodiek ofwel de standaard manier om om te gaan met versienummers van de standaard. De versioneringsmethodiek is gelijk voor alle 'gepubliceerde standaarden' die onder beheer zijn van Logius (afdeling standaarden) en is gebaseerd op Semver. Semver staat voor Semantisch Versioneren en we gebruiken versie 2.0.0 van de standaard zoals gepubliceerd op [specificatie van Semantisch Versioneren (SEMVER)](https://semver.org/lang/nl/#semantisch-versioneren-200). +Dat wil zeggen we kennen een bepaalde betekenis toe aan Major,Minor en Patch wijzigingen voor de standaarden zodanig dat de versienummers informatief zijn voor het type wijziging. Aandachtpunt hierbij is dat semantische versionering voor standaarden anders werkt dan semantische versionering voor software. De versienummers voor standaarden drukken uit of een (implementatie) van een oude versie van de standaard voldoet aan de regels van de nieuwe standaard (en dus compliant is aan de nieuwe versie) of niet. +Het voordeel van deze manier van versioneren is dat het versienummer signaleert of een implementatie van een bepaalde versie van de standaard voldoet aan een andere (nieuwe) versie van de standaard of dat er sprake is van nieuwe / gewijzigde regels waar aktie op moet worden ondernomen om compliant te zijn aan deze versie. + De beschreven methodiek is van toepassing op de standaarden die Logius in beheer heeft. In de tekst worden Digikoppeling standaarden als voorbeeld aangehaald maar semantische versienummering is ook op de andere standaarden van toepassing. ## Versioneringsmethodiek @@ -8,6 +11,10 @@ Per document wordt met `[documentnaam] X.Y.Z` de versie aangegeven. Met `X.Y.Z` wordt gerefereerd aan major (X) en minor (Y) releases en (Z) patches, dit wordt hieronder toegelicht. +* MAJOR wordt verhoogd als de nieuwe versie van de standaard zodanig wijzigt dat uitwerkingen (implementaties) volgens de vorige versie van de standaard niet meer voldoen aan de normen/eisen van de nieuwe versie van de standaard. +* MINOR wordt verhoogd bij wijzigingen waarbij uitwerkingen (implementaties) volgens de vorige versie van de standaard ook voldoen aan de normen/eisen van de nieuwe versie van de standaard. +* PATCH wordt verhoogd bij correcties. + ### Patch Releases In een patchrelease worden wijzigingen doorgevoerd die de technische specificatie niet raken. Dit kunnen tekstuele wijzigingen zijn of @@ -20,26 +27,22 @@ Een nieuwe patchrelease vervangt een eerdere versie in zijn geheel. ### Minor releases Een minor release geeft aan dat de nieuwe versie van de standaard zodanig is gewijzigd dat een implementatie van de voorgaande versie van de standaard voldoet aan de regels van de nieuwe versie. In een minor release kunnen wijzigingen doorgevoerd worden die de technische specificatie van een koppelvlak raken. Dat kunnen fouten zijn in de specificatie -zijn, het verzwaren of verlichten van een restrictie of een aanpassing van -een beveiligingstandaard (zoals TLS 1.0 naar TLS 1.2). In de SEMVER aanpak zijn +zijn of bv het verlichten van een restrictie. In de SEMVER aanpak voor software zijn minor releases technisch backwards compatible. Voor de uitwisselingsstandaarden zoals Digikoppeling is backwards compatibility lastiger te bepalen omdat uiteindelijk twee partijen met elkaar moeten meebewegen. -**Minor Releases kunnen dus mogelijk backwards incompatible zijn**. +**Minor Releases kunnen dus mogelijk technisch backwards incompatible zijn**. Voor Minor Releases wordt een uitgebreid vaststellingsprocedure gevolgd (conform het beheermodel van de standaard) en er kan in overleg met de deelnemers van het Technisch Overleg tot een migratiepad worden besloten. Dit migratiepad wordt in de release meegenomen. ### Major Releases -Er zijn twee Major release momenten: de overgang naar nieuwe externe -(meestal internationale) standaarden binnen een bestaand profiel, of de -toevoeging van een geheel nieuw profiel. In het eerste geval komt er een -nieuw major versie van het specificatie document vast te stellen volgens -het de uitgebreide vaststellingsprocedure. In het tweede geval wordt er -een *geheel nieuw* document toegevoegd aan de standaard. Als hierbij het +Een major release geeft aan dat de nieuwe versie van de standaard zodanig is gewijzigd dat een implementatie van de voorgaande versie van de standaard **niet** voldoet aan de regels van de nieuwe versie. +Bijvoorbeeld de overgang naar nieuwe externe +(meestal internationale) standaarden binnen een bestaand profiel. Als hierbij het functionele toepassingsgebied van de standaard, waarvoor het pas-toe-of-leg-uit -regime geldt, veranderd, dan wordt eerst de uitgebreide vaststellingsprocedure +regime geldt, verandert, dan wordt eerst de uitgebreide vaststellingsprocedure gevolgd en vervolgens de procedure van het Forum Standaardisatie.