Publiceren van een ReSpec document

Dit hoofdstuk beschrijft hoe je een ReSpec document publiceert op: docs.geostandaarden.nl.

Controles voor publicatie

Publicatie is grotendeel geautomatiseerd als aan de volgende voorwaarden is voldaan:

  • de folderstructuur van de repository waarin het ReSpec document staat, moet conform de Geonovum ReSpec template zijn
    • dat wil zeggen, index.html in de root folder, config.js in /js folder, afbeeldingen in /media en/of /data/Images folder;
  • de github repository mag maar één ReSpec document bevatten.

In het proces wordt op het volgende gecontroleerd: - Controleer op WCAG (web toegankelijkheids-) regels. Bij het pushen van een ReSpec document naar GitHub wordt automatisch een WCAG rapport geschreven. Dit is te vinden onder 'Actions'. Kies hier de commit die je gedaan hebt en je ziet daar 'build/WCAG Accessibility Check'). Deze controle checkt ook de HTML. - Controleer op Broken links. Bij het pushen van een ReSpec document naar GitHub wordt automatisch op broken links gecontroleerd. Dit is te vinden onder 'Actions'. Kies hier de commit die je gedaan hebt en je ziet daar 'Build/Link validation').

Actie voor publiceren van een Consultatie versie (CV)

  1. In 'js/config.js':
    • specStatus:"cv"
    • publishDate: moet ingevuld zijn met de datum van publicatie van de. "jjjj-mm-dd",
    • Shortname: moet ingevuld zijn met korte naam voor het document. Dit wordt onderdeel van de URL. Moet uniek zijn binnen pubdomain (afgezien van versies).
      • Als er al eerder een versie gepubliceerd is (stabiele versie, dus afgezien van de werkversie in github), kan Respec bovenin een document de navigatie naar vorige versie goed genereren. Daarvoor moet je ook invullen:
      • Previousmaturity: wat de status toen was.
      • previousPublishDate: wat de status toen was.
  2. Commit je wijzigingen en push de commit.
  3. Maak op github een Release. De automatische workflow maakt dan een pull request voor https://github.com/Geonovum/docs.geostandaarden.nl aan.
  4. Eén van de reviewers Frank Terpstra, Linda van den Brink of Wilko Quak checkt de publicatie. Als alles goed is bevonden wordt het document vervolgens automatisch gepubliceerd op docs.geostandaarden.nl.
  5. Na succesvolle publicatie:
    • zet de specStatus in config.js terug op "wv"
    • Vul previousMaturity in met "cv"
    • Vul previousPublishDate in met de datum van de zojuist gepubliceerde consultatieversie

Acties voor publiceren van een Vastellingsversie versie (VV)

  1. Edit en controleer config.js - configureer alles goed voor een vaststellingsversie
    • specStatus: "vv"
    • publishDate: moet ingevuld zijn met de datum van publicatie van de consultatieversie. "jjjj-mm-dd",
    • Shortname: moet ingevuld zijn met korte naam voor het document. Dit wordt onderdeel van de URL. Moet uniek zijn binnen pubdomain (afgezien van versies).
      • Als er al eerder een versie gepubliceerd is (stabiele versie, dus afgezien van de werkversie in github), kan Respec bovenin een document de navigatie naar vorige versie goed genereren. Daarvoor moet je ook invullen:
      • Previousmaturity: wat de status toen was.
      • Previousmaturity: wat de status toen was.
  2. Commit je wijzigingen en push de commit.
  3. Maak op github een Release. De automatische workflow maakt dan een pull request voor https://github.com/Geonovum/docs.geostandaarden.nl aan.
  4. Eén van de reviewers Frank Terpstra, Linda van den Brink of Wilko Quak checkt de publicatie. Als alles goed is bevonden wordt het document vervolgens automatisch gepubliceerd op docs.geostandaarden.nl.
  5. Na succesvolle publicatie:
    • zet de specStatus in config.js terug op WV
    • Vul previousMaturity in met CV
    • Vul previousPublishDate in met de datum van de zojuist gepubliceerde consultatieversie

Acties voor het publiceren van een Definitieve versie (DEF) maken

  1. Zet in config.js alles goed voor een definitieve versie
    • specStatus: "def",
    • publishDate: de publicatiedatum van de definitieve versie. "jjjj-mm-dd",
    • Shortname: korte naam voor het document. Dit wordt onderdeel van de URL. Moet uniek zijn binnen pubdomain (afgezien van versies).
    • Als er al eerder een versie gepubliceerd is (stabiele versie, dus afgezien van de werkversie in github), kan Respec bovenin een document de navigatie naar vorige versie goed genereren. Daarvoor moet je ook invullen:
      • Previousmaturity: wat de status toen was.
      • previousPublishDate: vorige publicatiedatum (jjjj-mm-dd)
  2. Commit je wijzigingen en push de commit.
  3. Maak op github een Release. De automatische workflow maakt dan een pull request voor https://github.com/Geonovum/docs.geostandaarden.nl aan.
  4. Eén van de reviewers Frank Terpstra, Linda van den Brink of Wilko Quak checkt de publicatie. Als alles goed is bevonden wordt het document vervolgens automatisch gepubliceerd op docs.geostandaarden.nl.
  5. Na succesvolle publicatie:
    • zet de specStatus in config.js terug op WV
    • Vul previousMaturity in met DEF
    • Vul previousPublishDate in met de datum van de zojuist gepubliceerde definitieve versie

Noot: Automatisch publiceren werkt alleen in Github repositories waar, conform de werkwijze, maar één ReSpec document in staat.

Als er meerdere Respec documenten in een repository staan kun je handmatig publiceren.

Automatisch publiceren via de workflow

De automatische workflow gaat aan het werk bij elke keer dat je een Release aanmaakt in github. De stappen om een ReSpec document te publiceren naar docs.geostandaarden.nl via de workflow zijn als volgt:

  1. configureer je document op de juiste manier (zie Publiceren in ReSpec en commit je wijzigingen.
    1. Er wordt een HTML snapshot aangemaakt via ReSpec
    2. (optioneel) PDF wordt gegenereerd indien je dit geconfigureerd hebt
    3. WCAG (web toegankelijkheidseisen) en HTML worden gevalideerd
    4. Links worden gecontroleerd
  2. Bekijk de resultaten van de controles via het tabblad Actions van de repository. Als er fouten gevonden zijn, los deze dan op en herhaal stap 1, of vraag om hulp.
  3. (optioneel) maak een Pre-release aan in de github repository.
    • Het ReSpec document wordt automatisch gepubliceerd op test.docs.geostandaarden.nl. Je kunt het hier bekijken om te zien of alles goed is gegaan.
  4. Maak een Release aan in de github repository (zie Publiceren in ReSpec voor meer informatie).
    • Er wordt automatisch een Pull Request (PR) aangemaakt naar: Geonovum/docs.geostandaarden.nl
    • Na goedkeuring van de PR (door Wilko, Frank of Linda) wordt het document gepubliceerd op: https://docs.geostandaarden.nl/

Meer documentatie staat in de readme van NL-ReSpec-template.

Configureren van de automatische workflow

Bij het maken van een nieuw ReSpec document via de template wordt de workflow automatisch geïnstalleerd. In github repositories die al een ReSpec document hadden voordat de nieuwe publicatieworkflow werd geïntroduceerd, is de workflow meestal ook al geinstalleerd. Alle actieve repositories waar een 'js/config.js' in gevonden is, hebben de nieuwe workflow gekregen.

Je kan controleren of de workflow is geïnstalleerd door bovenin de README.md in je repository te kijken. Hier moet in staan:

Deze repository is automatisch bijgewerkt naar de nieuwste workflow. Voor vragen, neem contact op met Linda van den Brink of Wilko Quak. Als je een nieuwe publicatie wilt starten, lees dan eerst de instructies in de README van de NL-ReSpec-template: https://github.com/Geonovum/NL-ReSpec-template.

Als de workflow niet automatisch is geïnstalleerd, kun je dit zelf doen. Dit is een eenmalige stap. Mocht dit niet lukken, dan kan Linda, Wilko of Matthijs erbij helpen:

Zorg dat Git is geïnstalleerd en beschikbaar is in je terminal

  1. Open de Opdrachtprompt:
    • ➜ Druk op de Windows-knop, typ cmd, druk op Enter
  2. Typ vervolgens in de cmd terminal:
    • git --version
    • Zie je een versie zoals git version 2.x.x, dan is alles goed.
  3. Krijg je een foutmelding zoals 'git' is not recognized as an internal or external command, dan moet je Git nog installeren via: https://git-scm.com/downloads/win

Vervolg, na installatie van git

  1. Navigeer naar de repository in Verkenner
  2. Open de map waarin de repository staat
    • Shift + rechter muisklik in een lege ruimte in de map
    • Kies "PowerShell-venster hier openen" of "Open in terminal"
  3. Download en voer het script uit. Kopieer en plak de volgende regels in PowerShell, voer ze om beuren uit:
    1. curl -o replace_workflow-local.ps1 https://raw.githubusercontent.com/Geonovum/NL-ReSpec-template/main/replace_workflow-local.ps1
    2. Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
    3. .\replace_workflow-local.ps1
  4. Als er geen errors verschijnen is dit gelukt. Je kunt dit checken door README.md te openen: als het goed is staat hier nu bovenin een tekst die begint met "Deze repository is automatisch bijgewerkt..."

Tenslotte

  1. Verwijder het bestand "replace_workflow-local.ps1"

'Handmatig' publiceren van respec document.

Het ‘handmatige’ publicatieproces voor docs.geostandaarden.nl is als volgt: