In dit document worden de stappen beschreven voor het publiceren van de technische bestanden van een informatiemodel in het Technisch register van geonovum(http://register.geostandaarden.nl). Met technische bestanden worden bedoeld: Informatiemodellen (in XMI of EAP), GML applicatieschema’s XML schema’s, schematron gebaseerde regels, waardelijsten, WSDLs, visualisaties(SLDs) en symbolen. Er is vanuit gegaan dat raadplegers van dit document een github account hebben aangemaakt en dat ze de GITHub userinterfase hebben geïnstalleerd.
Op hoofdlijnen werkt dit proces als volgt:
Om technische bestanden van een informatiemodel in het technisch register te kunnen publiceren dient allereerst een repository in Github te worden aangemaakt. Het is ook mogelijk een eerder aangemaakt repository te hergebruiken. Een volgende stap is het vullen van de repository. Hiervoor dient de gewenste repository naar een lokale map te worden gecloned en vervolgens volgens het voorgeschreven formaat te worden gevuld. Vervolgens zal het repository op de juiste manier geconfigureerd moeten worden om automatisch uploaden op het technisch-register mogelijk te maken. Wanneer dit gebeurt is dient het informatie model binnen het technisch register geregistreerd te worden. Dit kan zowel via de GeoNovum helpdesk als via github gedaan worden. Wanneer alle bovenstaande stappen zijn voltooid kan tenslotte de release worden uitgebracht.
In de komende hoofdstukken wordt dit stap voor stap uitgelegd.
Creëer een nieuwe repository in GitHub.com:
Clone de repository naar de gewenste lokale folder:
-
Open de GitHub desktop User Interface, druk links boven op het plusje en selecteer ‘Clone’
-
Selecteer de gewenste repository en druk op ‘Clone <naam van geselecteerde repository>’
- Selecteer de gewenste map waar de repository lokaal moet worden opgeslagen en druk op OK.
De gekloonde repository bevind zich nu in de gewenste lokale map. De gewenste bestanden en mappen kunnen nu eenvoudig worden toegevoegd aan de gekloonde repository. Hierbij is het van belang het hieronder beschreven formaat aan te houden.
In GitHub wordt het volgende folder formaat voorgeschreven om succesvol te kunnen synchroniseren met het technisch register:
/<artefact-type>/<versie>/<bestandsnaam>
Waarbij <artefact-type> één van de volgende kan zijn:
-
informatiemodel
-
gmlapplicatieschema
-
xmlschema
-
regels
-
waardelijst
-
wsdl
-
visualisatie
-
symbool
<Versie> is volledig vrij maar waar mogelijk raden we aan om volgens BOMOS[1] te werken. Dat wil zeggen:
“Versiebeleid met onderscheid tussen major (functionaliteit aanpassing), minor (kleine verbeteringen) en bug fixes is noodzakelijk.”
Bijvoorbeeld 1.0.1
Voor <bestandsnaam> geldt dat hier de per artefacttype de volgende extensie(s) worden verwacht:
| Artefact-type | Bestands extensie |
|---|---|
| Informatiemodel | .xmi, .eap |
| Gmlapplicatieschema | .xsd |
| Xmlschema | .xsd .wsdl [2] |
| Regels | .sch |
| Waardelijst | .xls .pdf .doc .rdf .xml |
| Wsdl | .wsdl |
| Visualisatie | .xml[3] |
| Symbool | .eps .png .svg |
1.0Voor meer informatie over de inhoud van het technisch register zie het document “20150914BeschrijvingConceptEnTechnischRegister”.
Wanneer de relevante folders en mappen uit het Technisch register aan het lokale repository zijn toegevoegd kan verder worden gegaan met de volgende stappen.
Om de aan de repository toegevoegde bestanden en mappen te zien klik op de betreffende repository en klik vervolgens op ‘Changes’ .
Zorg vervolgens dat alle ‘changes’ staan aangevinkt, dat in ‘summary’ een korte samenvatting staat van de veranderingen die zijn aangebracht, en druk op ‘commit to master’
- Druk vervolgens op Sync om de lokale repository en de GitHub repository te synchroniseren.
De relevante folders en mappen uit het technisch register staan nu op GitHub.
Voorwaarde is dat je een github repository volgens het juiste formaat reeds hebt aangemaakt en dat je hier admin rechten op hebt. Admin rechten worden verkregen door als owner te zijn ingeschreven voor het repository. Admin rechten op een niet zelf aangemaakt repository kunnen worden verkregen door contact op te nemen met de owner van het repository.
Ga in de repository die je wil koppelen naar settings:
Vervolgens naar webhooks & services:
Klik op add webhook:
Vul je password in:
Vul de url https://register.geostandaarden.nl/autodeploy/releasecreated.php in, selecteer “let me select individual elements” haal het vinkje bij “Push” weg en voeg er een toe bij “release” klik tot slot op add webhook zoals hieronder aangegeven:
Stuur een mail naar de geonovum helpdesk([email protected]) en vermeld daarin de volgende informatie:
-
Naam informatiemodel (bijvoorbeeld IMGolf)
-
Korte omschrijving in maximaal 58 karakters (bijvoorbeeld “Informatiemodel Golf”)
-
Lange omschrijving (bijvoorbeeld “In het informatiemodel golf wordt door Geonovum als voorbeeld informatiemodel gebruikt en bevat een beschrijving van golfbanen”
-
URL github repository (bijvoorbeeld http://github.com/Geonovum/IMGolf)
Ga naar de github pagina van Geonovum en selecteer het ‘Technisch-register’ repository. Klik vervolgens op Fork rechts boven in het scherm.
Het ‘technisch register’ repository verschijnt nu op uw eigen GitHub pagina:
Clone de repository via de GitHub desktop UserInterface:
Onderstaand venster verschijnt. Selecteer hierin het gewenste bestand waar het technisch register naartoe gecloned zal worden:
Open in het gekloonde repository het bestand ‘repos.json’. Voeg in dit bestand de gewenste informatie over het model toe sla het bestand op.
In de GitHub desktop UserInterface druk op changes, zorg dat alle veranderingen geselecteerd zijn, vul een summary in van de verandering in en druk op ‘Commit to master’
Druk vervolgens op sync in de rechter bovenhoek
Na het uitvoeren van bovenstaande stap: ga naar uw GitHub pagina en druk daar in de repository ‘Technisch register’ op het pull request logo. Zorg ervoor dat deze actie wordt uitgevoerd op de meest recente versie van het target repository . Dit is automatisch het geval wanneer de in de voorgaande stap beschreven ‘Sync’ correct is uitgevoerd.
Druk vervolgens op ‘view pull request’. Het kan zijn dat het scherm afwijkt van onderstaande voorbeeld doordat de melding “Can’t automatically merge…” verschijnt. Mogelijk wordt dit veroorzaakt doordat de eerder beschreven ‘Sync’ niet goed of te lang geleden is uitgevoerd. Voor het verdere verloop van het proces maakt dit echter niet uit.
Om een release te kunnen uitbrengen moeten de informatiemodellen bekend zijn bij het ‘Technisch Register’. Het bekend maken van het informatie model bij het ‘Technisch Register begint door het aanleveren van een beschrijvende tekst zoals beschreven in de voorgaande sectie van deze handleiding. Wanneer de aangeleverde beschrijvende tekst is verwerkt ontvangt u hierover een mail. De volgende stappen dienen pas te worden uitgevoerd na ontvangst van deze mail.
- Ga naar Repositories en klik op de gewenste repository
Klik op releases. Het getal voor releases geeft aan hoeveel releases al zijn uitgebracht en kan afwijken van het getal in onderstaande voorbeeld.
Onderstaande scherm verschijnt in het geval er nog niet eerder een release van het repository is uitgebracht. Klik hierin op ‘Create a new release’
In het geval er al eerder releases zijn uitgebracht zal het onderstaande scherm verschijnen. Klik hierin op “draft a new version”.
Vul bij ‘Tag version’ het versie nummer van de release in. Volg hierbij de aanwijzingen onder ‘Tagging suggestions’ en ‘Semantic versioning’.
Geef de Testrelease een titel en een beschrijving mee en zorg dat ‘This is a pre-release’ is aangevinkt.
Druk tenslotte op ‘Publish release’
Ga naar Repositories en klik op de gewenste repository
Klik op releases. Het getal voor releases geeft aan hoeveel releases al zijn uitgebracht en kan afwijken van het getal in onderstaande voorbeeld.
Onderstaande scherm verschijnt in het geval er nog niet eerder een release van het repository is uitgebracht. Klik hierin op ‘Create a new release’
In het geval er al eerder releases zijn uitgebracht zal het onderstaande scherm verschijnen. Vanaf hier kan er een release worden aangemaakt voor productie. Een tweede optie is het aanmaken van een productie release door een bestaande pre-release te veranderen naar een productie release. In deze handleiding is er vanuit gegaan dat het aanmaken van een nieuwe productie release de standaard procedure is. De alternatieve procedure is te vinden in de bijlage.
In het geval een nieuwe release direct in productie moet worden gebracht: Klik in het scherm op “draft a new version”.
Vul bij ‘Tag version’ het versie nummer van de release in. Volg hierbij de aanwijzingen onder ‘Tagging suggestions’ en ‘Semantic versioning’.
Geef de Testrelease een titel en een beschrijving mee en zorg dat ‘This is a pre-release’ niet is aangevinkt.
Druk tenslotte op ‘Publish release’
Om een bestaande pre-release in productie te brengen: Klik op de ‘Edit’ button behorend bij het bestaande release.
Als alternatief voor een nieuwe release is het ook mogelijk een bestaande (pre) release te editen. Klik bij releases op de release welke je wil aanpassen (bijvoorbeeld een pre-release die naar productie gaat) op de edit knop.
Pas de tag en titel en eventueel de begeleidende tekst aan en klik op update release.
[1] https://www.forumstandaardisatie.nl/fileadmin/os/publicaties/HR\_BOMOS\_\_FINAL\_web.pdf
[2] Kan ook nog een verdere folder structuur bevatten, meestal de inhoud van een zip met schema informatie zoals geleverd bij StUF uitwisselingen.
[3] Kan ook nog verdere folder structuur bevatten