Merge pull request #10 from Logius-standaarden/develop

Develop naar main

.github/ISSUE_TEMPLATE/aanpassing_documentatie.yml

@@ -0,0 +1,43 @@
+name: Aanpassing op documentatie
+description: Stel een (tekstueele) wijziging voor in de documentatie van de Digikoppeling standaard
+title: "RFC ..."
+labels: ["digikoppeling", "documentatie"]
+body:
+  - type: checkboxes
+    id: standaard
+    attributes:
+      label: Soort
+      description: Om wat voor wijziging gaat het?
+      options:
+        - label: Tekstuele fout
+        - label: Verbetersuggestie
+        - label: Onduidelijke tekst
+  - type: textarea
+    id: omschrijving
+    attributes:
+      label: Omschrijving
+      description: Wat is de voorgestelde wijziging? Op welke pagina of sectie staat het?
+      placeholder: Tik hier uw voorgestelde wijziging
+    validations:
+      required: true
+  - type: input
+    id: contact
+    attributes:
+      label: Naam
+      description: Naam. Uw naam wordt online getoond in het issue. U kunt ook anoniem invullem.
+    validations:
+      required: false
+  - type: input
+    id: email
+    attributes:
+      label: Email
+      description: E-mail adres. Uw e-mail adres wordt online getoond in het issue. U kunt ook anoniem invullem.
+    validations:
+      required: false
+  - type: input
+    id: organisatie
+    attributes:
+      label: Organisatie
+      description: Naam van uw organisatie. Dit veld is verplicht omdat we deze in het overzicht opnemen.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/wijzigingsformulier.yml

@@ -0,0 +1,34 @@
+name: Wijzigingsformulier
+description: Stel een (inhoudelijke) wijziging voor op de Digikoppeling standaard. Voor een tekstueele wijziging op de documentatie bestaat een ander formulier.
+title: "RFC ..."
+labels: ["Standaard: digikoppeling", "Type: wijziging"]
+body:
+  - type: textarea
+    id: omschrijving
+    attributes:
+      label: Omschrijving
+      description: Wat is de voorgestelde wijziging? 
+      placeholder: Vul hier de voorgestelde aanpassing in
+    validations:
+      required: true
+  - type: input
+    id: contact
+    attributes:
+      label: Naam
+      description: Naam. Uw naam wordt online getoond in het issue. U kunt ook anoniem invullem.
+    validations:
+      required: false
+  - type: input
+    id: email
+    attributes:
+      label: Email
+      description: E-mail adres. Uw e-mail adres wordt online getoond in het issue. U kunt ook anoniem invullem.
+    validations:
+      required: false
+  - type: input
+    id: organisatie
+    attributes:
+      label: Organisatie
+      description: Naam van uw organisatie. Dit veld is verplicht omdat we deze in het overzicht opnemen.
+    validations:
+      required: true

.github/workflows/build.yml

@@ -1,44 +1,20 @@
-name: Build and Check
-on:
-  workflow_dispatch:
-  pull_request:
-jobs:
-  build:
-    name: Build
-    uses: Logius-standaarden/Automatisering/.github/workflows/build.yml@main
-  check:
-    needs: build
-    name: Check
-    uses: Logius-standaarden/Automatisering/.github/workflows/check.yml@main
-
-  preview:
-    needs: build
-    name: Preview
-    runs-on: ubuntu-latest
-    if: ${{ github.event_name == 'pull_request' && !github.event.pull_request.head.repo.fork }}
-    steps:
-      - uses: actions/checkout@v2
-      - name: Recover HTML
-        uses: actions/cache@v2
-        with:
-          path: ~/static
-          key: ${{ github.run_id }}      
-      - name: Gather files
-        run: |
-         rm index.html
-         mv ~/static/snapshot.html index.html
-         rm -f *.md *.pdf *.js snapshot.html
-         mkdir ~/content
-         mv ./* ~/content
-         git clone https://user:${{ secrets.BEHEER }}@github.com/Logius-standaarden/Publicatie-Preview.git
-      - name: Commit preview
-        run: |
-         cd Publicatie-Preview
-         rm -f -r ${{ github.event.repository.name }}/${{ github.head_ref }}
-         mkdir -p ${{ github.event.repository.name }}/${{ github.head_ref }}
-         mv ~/content/* ${{ github.event.repository.name }}/${{ github.head_ref }}
-         git add -A
-         git config user.name "GitHub Action"
-         git config user.email "api@logius.nl"
-         git commit -m "new preview build"
-         git push
+name: Build and Check
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+jobs:
+  build:
+    name: Build
+    uses: Logius-standaarden/Automatisering/.github/workflows/build.yml@main
+  check:
+    needs: build
+    name: Check
+    uses: Logius-standaarden/Automatisering/.github/workflows/check.yml@main    
+  publish:
+    needs: build
+    name: Publish (Logius)
+    uses: Logius-standaarden/Automatisering/.github/workflows/publish.yml@main
+    secrets: inherit

README.md

@@ -1,8 +1,30 @@
-# Template voor een standaard
+# Beheermodel voor het Beheer- en Ontwikkelmodel Open Standaarden (BOMOS)
 
-Gebruik deze template repository voor nieuwe specificaties
-zie
+Dit document maakt deel uit van de BOMOS documentatie. Deze bestaat uit
+2 basisdocumenten, aanvullende modules en ondersteunende documenten. Alle
+documentatie is te vinden via de Logius website. Hier staan de repositories
+waaruit de documentatie gegeneerd wordt.
+- [BOMOS Fundament](https://www.github.com/Logius-standaarden/BOMOS-Fundament)
+  beschrijft de basis en achtergronden van BOMOS.
+- [BOMOS Verdieping](https://www.github.com/Logius-standaarden/BOMOS-Verdieping),
+  hierin worden de modules nader uitgewerkt.
+- [BOMOS Stelsels](https://www.github.com/Logius-standaarden/BOMOS-Stelsels),
+  aanvullende module over stelselbeheer.
+- [BOMOS Linked Data](https://www.github.com/Logius-standaarden/BOMOS-LinkedData),
+  aanvullende module met BOMOS aspecten die specifiek over linked data gaan.
+- [BOMOS Beheermodel](https://www.github.com/Logius-standaarden/BOMOS-Beheermodel),
+  deze repository
 
-- html: https://logius-standaarden.github.io/BOMOS-Beheermodel/
-- html(static): https://logius-standaarden.github.io/BOMOS-Beheermodel/snapshot.html
-- [PDF-versie](https://github.com/Logius-standaarden/BOMOS-Beheermodel/blob/develop/doc.pdf)
+Dit beheermodel beschrijft hoe Logius BOMOS zelf beheert. Net als de standaarden
+die we volgens BOMOS beheren moet ook BOMOS zelf beheerd worden en ook daarvoor
+passen we de BOMOS principes toe.
+
+De ontwikkelversies staan online.
+- [Dynamische pagina (actueel)](https://Logius-standaarden.github.io/BOMOS-Beheermodel/index.html)
+- [Statische pagina (laatste build)](https://Logius-standaarden.github.io/BOMOS-Beheermodel/snapshot.html)
+- [PDF versie](https://logius-standaarden.github.io/BOMOS-Verdieping/BOMOS-Beheermodel.pdf)
+
+Iedereen is vrij om wijzigingen voor te stellen op de BOMOS documentatie.
+Een wijziging gemaakt in github kan als _issue_ worden ingediend worden of
+een (gewijzigde) file kan als _pull request_ ingediend worden
+en door Logius worden overgenomen.

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

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

bijlage03_Versienummering.md

@@ -1,13 +1,20 @@
 # 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
 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.
 
 <aside class="example" title="Grote wijzigingen voor Digikoppeling">
@@ -60,12 +63,14 @@ Voor standaarden is relevant of een realisatie volgens de oude versie van een st
 Globale regels voor het bepalen van de impact op de versionering:
 
 - Toevoegen = Major
-- Wijzingen :
-	- Versoepeling = Minor
-	- Verscherping = Major
+- Wijzigingen = Major of Minor (afhankelijk van de verwachte impact van de wijziging)
 - Verwijderen = Minor
 - Correctie = Patch
 
+Voor standaarden waarbij wijzigingen op onderdelen kan verschillen tussen 
+major en minor kan een impactmatrix opgesteld worden waarmee impact op de 
+onderdelen gespecificeerd kan worden.
+
 ## Versie overgangen
 
 Wanneer een nieuwe major versie uitkomt zal de oude versie conform de afgestemde migratiepad een einddatum van geldigheid krijgen. In de overgangsperiode kunnen dus meerdere versies gepubliceerd zijn en de status geldig hebben.