1 over

Om het functioneren en de activiteiten die plaats vinden in het Schelde estuarium te evalueren, hebben Vlaanderen en Nederland samengewerkt om een methodiek te ontwikkelen die gebruikt maakt van indicatoren om de staat van het estuarium te beoordelen. Deze evaluatie wordt om de zes jaar uitgevoerd in samenwerking met verschillende partners en leden van de projectgroep ‘Evaluatie en Rapportage’ (PG ER) van de Vlaams-Nederlandse Schelde Commissie (VNSC). Een derde deel van deze evaluatie is in voordbereiding voor T2021, die gebaseerd is op de T2015 evaluatie en de T2009 baseline.

Ervaringen in eerdere rapporten hebben uitgewezen dat een centraal beheer van bestanden en scripts, en het correct toepassen van versiebeheer, van groot belang zijn om de leesbaarheid, duidelijkheid en reproduceerbaarheid van de uitgevoerde evaluatie te verzekeren. Daarom heeft het ScheldeMonitor data- en informatieportaal de opdracht gekregen om een GitHub-repository op te stellen voor alle analyses uitgevoerd voor het T2021-rapport. Deze repository is beschikbaar in de ScheldeMonitor GitHub organisatiie.

Deze handleiding werd gemaakt om ervoor te zorgen dat het gebruik van deze repository uniform en consistent is. Om dit te bereiken bevat de handleiding richtlijnen en regels over de werkwijze, inhoud management en structuur.

Aangezien het informatie- en dataportaal van ScheldeMonitor een RStudio omgeving bevat die bedoeld is om te worden gebruikt in combinatie met deze GitHub repository, is deze handleiding voornamelijk voor R gebruikers opgesteld. Meerdere richtlijnen kunnen echter ook in andere programmeertalen worden gebruikt. Voor sommige secties is de inhoud gebaseerd op de RStudio handleiding die beschikbaar is op de ScheldeMonitor website. De belangrijkste secties worden ook aangeduid in het ‘ReadMe’ bestand van de repository.

2 Toegang tot de T2021 GitHub repository

2.1 Toegang aanvragen

GitHub is een code-hosting platform voor versiebeheer en samenwerking dat het gemakkelijkst toegankelijk is via een webbrowser op https://github.com/. Hiermee kunnen gebruikers vanaf elke locatie samenwerken aan projecten. GitHub projecten worden opgeslagen als ‘repositories’, die ofwel publiekelijk ofwel privaat zichtbaar zijn.

De T2021 private GitHub is een private repository binnen de ‘ScheldeMonitor’ GitHub organisatie. Dit betekent dat de organisatie zichtbaar is in GitHub, maar de repository toch verborgen is voor niet-leden.

Onderzoekers, leden van VNSC of hun werkgroepen, en partner instituten van ScheldeMonitor kunnen toegang aanvragen voor de ScheldeMonitor GitHub organisatie, of voor één specifieke openbare of private repository.

Om dit te doen kunnen gebruikers een mail sturen naar met als onderwerp ‘ScheldeMonitor GitHub’, en de antwoorden op volgende vragen:

  • Naam en GitHub gebruikersnaam?
  • Bent u lid van VNSC of van één van de werkingsgroepen?
  • Wilt u toegang tot specifieke repositories, en waarom?
  • Met welk instituut bent u verbonden?
  • Heeft u een specifiek niveau van toestemming nodig (zie Regels voor de repository van T2021)?

2.2 Toegangsbeheer

Met de gegeven informatie zal de helpdesk van ScheldeMonitor controleren als er toegang kan gegeven worden voor de gebruiker of niet. Dit betekent dat de gebruiker twee verschillende ‘rollen’ krijgt toegewezen, één binnen de ‘ScheldeMonitor’ GitHub organisatie en één binnen een gekozen repository, die elk een andere set rechten toekennen.

2.2.1 Toegang tot de organisatie

Wanneer u in aanmerking komt voor een lidmaatschap van de ScheldMonitor GitHub organisatie, kan de gebruiker een ‘eigenaar’ of ‘lid’ status toegewezen krijgen. Indien niet wordt de gebruiker beschouwd als een ‘externe medewerker’ en zal enkel toegang krijgen tot de gevraagde repositories binnen de organisatie. De helpdesk van ScheldeMonitor en de VNSC worden standaard als eigenaars van de organisatie beschouwd. Het verschil tussen de eigenaar, lid of externe medewerker status wordt gegeven in de onderstaande tabellen:

Visibility Owner Member Outside collaborator
See organization X X X
See public repositories X X X
See private repositories X X
See members X X X
Change repository visibility X
Management Owner Member Outside collaborator
Manage members X
Manage collaborators X
Create public repository X
Create private repository X
Delete repositories X
Transfer repositories X
Base repository rights Owner Member Outside collaborator
Clone any repository X X
Pull any repository X X
Push/merge any repository X
Branch public repositories X X
Branch private repositories X
Interaction Owner Member Outside collaborator
Create discussions X X
Comment discussions X X
Delete issues X X
Create teams X X
Manage teams X X
Publish GitHub Pages sites X X

Leden kunnen toegevoegd worden aan een bepaald team binnen de organisatie. Het gebruik van teams maakt interne discussies, teamvermeldingen en opdrachten mogelijk, als ook het toevoegen van volledige teams aan bepaalde repositories in plaats van individuele leden en medewerkers. Deze teams kunnen per partner instituut of ten gunste van bepaalde werkgroepen van VNSC worden opgericht.

2.2.2 Toegang tot de repository

Hoewel organisatieleden basisleesrechten hebben, is het nog steeds nodig om gebruikers aan repositories toe te wijzen als medewerker om repository specifieke rechten te verlenen. Deze rechten hebben voorrang op de basisrechten die op organisatieniveau zijn ingesteld, wat betekent dat externe medewerkers lees- en schrijfrechten kunnen krijgen voor een specifieke repository zonder lid te moeten worden van de organisatie. De verschillende rollen voor een repository, en hun specifieke rechten worden weergegeven in de tabel hieronder:

Read Triage Write Maintain Admin
Pull repository X X X X X
Branch repository X X X X X
Clone repository X X X X X
Comment X X X X X
Manage issues X X X X X
Apply labels X X X X
Manage labels X X X
Push/merge repository X X X
Manage comments X X X
Change repository visibility X
Change repository settings X
Manage collaborators X

De medewerkers krijgen standaard een “Write” status om te kunnen werken aan nieuwe ontwikkelingen binnen de repository. De ScheldeMonitor helpdesk alsook de projectleiders zullen de “Admin” status krijgen om de bijdragen aan de repository te kunnen beheren.

3 Werken met een GitHub repository

De T2021 repository kan gezien worden als een ‘master folder’, waar alles wat met dit specifieke project te maken heeft, moet worden bewaard. Repositories, of ‘repo’s’, kunnen mappen bevatten, of uit aparte bestanden bestaan.

Het hebben van een GitHub repo maakt het voor gebruikers gemakkelijk om samenwerkings- en persoonlijke projecten bij te houden, aangezien alle bestanden die nodig zijn voor bepaalde analyses bij elkaar kunnen worden gehouden en mensen hun code, grafieken, enz. kunnen toevoegen terwijl de projecten zich ontwikkelen. Elk bestand op GitHub heeft een geschiedenis, waardoor het gemakkelijk is om wijzigingen te bekijken die er op verschillende tijdstippen in zijn aangebracht. U kunt de code van anderen bekijken, opmerkingen toevoegen aan bepaalde regels of het algemene document, en wijzigingen voorstellen.

Voor samenwerkingsprojecten kunt u met GitHub taken toewijzen aan verschillende gebruikers, zodat het duidelijk wordt wie verantwoordelijk is voor welk deel van de analyse. U kunt ook aan bepaalde gebruikers vragen om uw code te controleren. Voor persoonlijke projecten kunt u met versiebeheer uw werk bijhouden en gemakkelijk navigeren tussen de vele versies van bestanden die u gemaakt hebt, terwijl u ook een online back-up behoudt.

Dit hoofdstuk beschrijft hoe u de GitHub repository kunt gebruiken om alle scripts, documenten en databestanden te verzamelen die worden gebruikt om het T2021 rapport van het Schelde estuarium samen te stellen.

3.1 Installatie van Git

Eerst is een installatie van Git nodig op de persoonlijke hardware van de gebruiker om functies te verlenen die nodig zijn voor versiebeheer. Deze installatie verschilt tussen Windows en Mac hardware.

3.1.1 Windows

Indien de gebruiker Windows hardware gebruikt, download en installeer Git voor uw besturingssysteem. Hieronder zijn enkele aanbevolen installatie instructies:

     For “Select Components”, check:
  • “Git Bash Here”
  • “Git GUI Here”
  • “Git LFS (Large File Support)”
  • “Associate .git* …”
  • “Associate .sh …”
     When prompted to choose the default editor, select Nano (a simple terminal editor) or Notepad++ (a simple graphical editor):
     For “Adjust your PATH environment”, select: “Use Git from Git Bash only”
     For “Choose HTTPS transport backend”, select: “Use the OpenSSL library”
     For “Configure the line ending conversions”, select: “Checkout Windows-style,…”
     For “Configure the terminal emulator …”, select: “Use MinTTY …”
     For “Configure extra options”, select: “Enable file system caching”
     “Enable Git Credential Manager”

3.1.2 Mac

Als een gebruiker Mac software gebruikt, installeer Git dan via Homebrew, een pakketbeheerder voor command-line-programma’s op Mac. Open eerst een terminal, die gevonden kan worden op ~/Application/Utilities/Terminal.app. Kopieer en plak daarna deze lijn in de terminal en druk op “Enter”:

     /usr/bin/ruby -e “$(curl –fsSL https://raw.GitHUBusercontent.com/Homebrew/install/master/install)”

Voeg volgende code in om Git te installeren:

     brew install git

Volg alle instructies in het terminal venster, het kan zijn dat de gebruiker het wachtwoord van een Mac moet invoeren of akkoord moet gaan met vragen door “yes” te typen.

Nu Git geïnstalleerd is, kan de gebruiker versiebeheer gaan gebruiken voor zowel de interne projecten als met GitHub repositories.

3.2 Versiebeheer gebruiken met GitHub & RStudio

De GitHub werkwijze kan samengevat worden door de “pull-commit-push” mantra. Met deze methodologie heeft elk bestand op GitHub een geschiedenis. Dus in plaats van veel bestanden te hebben zoals scripts_1st_May.R, script_2nd_May.R, kan de gebruiker er maar één hebben. Door de geschiedenis ervan te verkennen, kan de gebruiker zien hoe het er op verschillende tijdstippen uitzag.

Omdat het de bedoeling is om de T2021 repository te gebruiken in combinatie met de RStudio omgeving van ScheldeMonitor, is het belangrijk om verbinding te maken tussen de repository en RStudio. Hoe u dit moet doen wordt in detail beschreven in de RStudio handleiding, beschikbaar in de GitHub repository of op de ScheldeMonitor website.

Eenmaal verbonden kan al het werk in de RStudio omgeving versie gecontroleerd worden uitgevoerd. De werkwijze om dit te doen wordt beschreven door de vijf stappen hieronder:

3.2.1 Een nieuwe projectbranch aanmaken

Het werken aan projecten gebeurt in ‘branches’. Een branch is een kopie, of versie van de project repository waarin wijzigingen kunnen worden aangebracht. Elk project start met de standaard ‘master’ branch. Deze branch moet door het hele project als rode draad worden behandeld en eindigen in het eindproduct. Het aantal rechtstreekse aanpassingen aan de masterbranch moet daarom gelimiteerd worden. Om nieuwe ontwikkelingen te maken, kan een nieuwe branch aangemaakt worden, die zich op die specifieke ontwikkelingen richten. Door deze methodologie te gebruiken, kunnen verschillende ontwikkelingen naast elkaar gestart worden, zonder dat dit invloed heeft op elkaar of de standaard master branch:

Een nieuwe branch maken kan het gemakkelijkst gedaan worden in het GitHub project repository online. Als u op de project webpagina bent, wordt de huidige gevisualiseerde branch boven de repository aangeduid: