To evaluate the functioning of the Scheldt Estuary and the activities that are held within, Flanders and The Netherlands have cooperated to develop a methodology that uses indicators to assess the state of the estuary. This evaluation is executed every six years in a cooperative action with several partners and the members of the ‘Evaluation and Reporting’ workgroup (PG ER) of the Flemish-Dutch Scheldt Commission (VNSC). A third installment of this evaluation is pending for T2021, which is built on the T2015 evaluation and the T2009 baseline.
Experiences in previous report have indicated that a centralized management of files and scripts, and the correct application of version control is of extreme importance to insure the readability, comprehensibility and reproducibility of the executed evaluation. Therefore, the ScheldeMonitor data and information portal has been given the assignment to set up a GitHub repository, dedicated to all analysis conducted for the T2021 report. This repository is available within the ScheldeMonitor GitHub organization.
This manual was created to ensure that the usage of this repository is uniform and consistent. To achieve this, the manual contains guidelines and rules on workflow, content management and structure.
As the ScheldeMonitor information and data portal holds an RStudio environment that is intended to be used in combination with this GitHub repository, this manual is created mainly for R-users. However, multiple guidelines can also be used in other programming languages. For some sections, the content is based on the RStudio manual that is available on the ScheldeMonitor website. The most important sections will also be highlighted in the ‘ReadMe’ file of the repository.
GitHub is a code-hosting platform for version control and collaboration that is most easily accessed through a web browser at https://github.com/. It lets users work together on projects from any location. GitHub projects are saved as ‘repositories’, being either publicly or privately visible.
The T2021 private GitHub is a private repository within the ‘ScheldeMonitor’ GitHub organization. This implies that organization is visible in GitHub, yet the repository is hidden from non-members.
Researchers, members of the VNSC or their working groups, and partners institutes of the ScheldeMonitor can request access to the ScheldeMonitor GitHub organization, or to one specific public or private repository.
To do so, users can send an email to email@example.com with topic ‘ScheldeMonitor GitHub’, and answers to the following questions:
With the given information, the helpdesk of ScheldeMonitor will check whether the user can be granted access or not. This implies that the user is designated with two separate ‘roles’, one within the ‘ScheldeMonitor’ GitHub organization and one within a chosen repository, each granting a different set of rights.
When eligible for membership within the ScheldeMonitor GitHub organization, a user can be granted either ‘owner’ or ‘member’ status. If not, the user is considered as an ‘outside collaborator’ and will only gain access to chosen repositories within the organization. By default, the helpdesk of ScheldeMonitor and the VNSC are considered as owners of the organization. The differences between the owner, member or outside collaborator status is given in the tables below:
|See public repositories||X||X||X|
|See private repositories||X||X|
|Change repository visibility||X|
|Create public repository||X|
|Create private repository||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|
|Publish GitHub Pages sites||X||X|
Members can be added to certain teams within the organization as well. Using teams allows for internal discussion, team mentions and assignments, as well as the addition of complete teams to certain repositories instead of individual members and collaborators. These teams can be created per partner institute or in favor of certain working groups of the VNSC.
Although organization members have base reading rights, it is still necessary to assign users to repositories as collaborators to grant repository-specific rights. These rights overrule the base rights established on the organization level, implying that outside collaborators can receive reading and writing rights for a specific repository without having to be a member of the organization. The different roles for a repository, and their specific rights, are given in the table below:
|Change repository visibility||X|
|Change repository settings||X|
By default, contributors are going to receive “Write” status to be able to work on new developments within a repository. The ScheldeMonitor helpdesk, as well as the project leaders, will be designated as “Admin” status to be able to manage the contributions made to the repository.
The T2021 repository can be seen as a ‘master folder’, where everything associated with this specific project should be kept. Repositories, or ‘repo’s’, can have folders within them, or just consist of separate files.
Having a GitHub repo makes it easy for users to keep track of collaborative and personal projects, as all files necessary for certain analyses can be held together and people can add in their code, graphs, etc. as the projects develop. Each file on GitHub has a history, making it easy to explore the changes that occurred to it at different time points. You can review other people’s code, add comments to certain lines or to the overall document, and suggest changes.
For collaborative projects, GitHub allows you to assign tasks to different users, making it clear who is responsible for which part of the analysis. You can also ask certain users to review your code. For personal projects, version control allows you to keep track of your work and easily navigate among the many versions of the files you create, whilst also maintaining an online backup.
This chapter describes how to start using the GitHub repository to assemble all scripts, documents and data files that are used to compose the T2021 report of the Scheldt estuary.
First, an installation of Git is needed on the personal hardware of the user, in orde to grant the functions that are necessary for version control. This installation differs between Windows and Mac hardware.
If a user is on Windows hardware, download and install Git for your operating system. Below are some recommended installation instructions:
If a user is on Mac software, install Git via Homebrew, which is a package manager for command line programs on Mac. First, open a terminal, which can be found at ~/Application/Utilities/Terminal.app. Then, copy and paste this line into the terminal and hit “Enter”:
Now enter the following to install Git:
Follow any instructions in the terminal window, the user may need to enter a Mac’s password or agree to questions by typing “yes”.
Now that Git is installed, the user can start using version control for both the internal projects as well as with GitHub repositories.
The GitHub workflow can be summarized by the “pull-commit-push” mantra. Using this methodology, each file on GitHub has a history. So instead of having many files like scripts_1st_May.R, script_2nd_May.R, the user can have only one. By exploring its history, the user can see what it looked like at different points in time.
As it is intended to use the T2021 repository in combination with the RStudio environment of ScheldeMonitor, it is important to make a connection between the repository and RStudio. How to do so is described in detail in the RStudio manual, available in the GitHub repository or on the ScheldeMonitor website.
Once connected, all work in the RStudio environment can be done in a version-controlled manner. The workflow to do so is described by the five steps below:
Working on projects is done in ‘branches’. A branch is a copy, or version, of the project repository in which edits can be made. Every project starts with the default ‘master’ branch. This branch should be treated as a red line throughout the project and end in the finalized product. Therefore, the number of direct edits to the master branch should be limited. To initiate new developments, new branches can be made that are dedicated to those specific developments. Using this methodology, several developments can be initiated aside one another, without affecting each other or the default master branch:
Creating a new branch can be done most easily in the GitHub project repository online. When on the project webpage, the currently visualized branch is indicated above the repository: