# How to use GIT@CIB-Traffic

The goal of this page is to give some guidelines (with occasional hard rules) on how we use GIT in our group. Things in **bold** are mandatory!

First, some useful references that should be looked at before following the instructions given here.

SET-IT has issued some guidance on how to use git. At the bottom of the following page you will find a collection tutorials/resources on how to get started.
https://icts.kuleuven.be/sc/english/collaboration/Gitlab

Tutorials on git are abundant on the internet, so feel free to consult some other sources.
Always remember: if you have a specific problem it's common that someone else stumbled on it before. Search engines are your friend.

https://gitlab.pages.gitlab.kuleuven.be/devops-example/
gives some motivation as to why researchers should bother with learning git in the first place.

There's also a course on version control offered by ICTS. (KU Loket>> Personnel >> Training >> search for version control). Focus for this is on command driven interactions with git tho and not for GUI applications like GitKraken or SourceTree. (If you have attended that course leave some feedback in this doc! Was it useful for you as a newcomer?)
# ITSCrealab

![](https://i.imgur.com/9sjXw1f.png "Entropy" =250x200)
https://gitlab.kuleuven.be/ITSCreaLab

The different projects in our group have a designated spot inside of the git project depending on their context. This document is meant to facilitate proper use and impose some common structure in how repositories are set up and managed.
The idea is for you to come back here when you're trying to figure out where
something should go within the ITScrealab group.

There are two overarching categories: Research and Education.
## Research
We loosely categorize contributions into five different classes:
Toolboxes, Collaborative Projects, Private Research Projects, Publications and Utilities.
### Public Toolbox
Public Toolboxes are pieces of software that we expose to the outside world for others to use and experiment with.
The requirements for a Toolbox are higher than for any other project, as a minimum the repository should contain:
- Some demonstrator/tutorials (either GUI, tutorials or notebooks)
- A quick start guide detailing what is necessary for others to run the tool on their machine
- An extensive readme that contains the quick start guide and some framing of the work
- Documentation - may be adequately covered by the demonstator

The toolboxes have different <ins>releases</ins>, see https://docs.gitlab.com/ee/user/project/releases/. These are basically tagged commits that work as intended and incorporate some meaningfull updates to the toolbox, e.g. a new functionality or major restructuring.

##### Using a toolbox in research
If you're reliant on the codes that are contained in the toolbox, the best practice is to link the latest release of the toolbox to your repository. Clearly state in the readme of your repository which of the releases you are using.

For most use cases, you will only need the functionality of the toolboxes. Which means that you should not add files to the directory of a public toolbox. If you think there is a need to change the functionality of a toolbox, you can edit those files. However, make a distinction between changes that are project-specific, that is you do not want to port them back to the toolbox itself, and changes that should be included in a future release of the toolbox. (See below on how to handle those changes.)

##### Extending a toolbox
If you want to extend the functionality of the tools in this group you work on a given branch and submit a merge request. That will eventually be reviewed by the repository owner. (You can also contact the repository owner for help.)

This [guide](https://medium.com/@porteneuve/mastering-git-subtrees-943d29a798ec) details the different options that you have for managing this workflow efficiently.
Basically you want to keep commits that are meant to be ported back to the toolbox separate from those that are repository specific.
This way you can simply fetch the file(s) associated with a specific commit from your repository to a development branch of the toolbox and submit a merge request.
Another option is to use diff tools to just make comparisons between the different folders and accept changes that you want to have transfered individually. IDEs such as Pycharm and Visual Studio often support this out of the box.

### Collaborative projects
As the name explains, these are projects where multiple people of our group are working on. These should go into the Group Projects subgroup in ITScrealab. Depending on the specific set up they can be groups themselves or repositories. They may be public or private. Examples of current and past projects that would qualify would be DUET or Concorda. It is up to the group itself to aggree on a good working method of using GIT.

### Research projects
These are private repositories that contain research that's being done as an individual with a clear purpose. Typically, they form the basis for what ends up in the Publications Group. But also crazy research ideas may be tested in such projects before they may ever be intergrated.

### Utilities & Miscellaneous
A group that contains various *useful* code snippets that do not neatly fit in with the other categories. This could be a script that extracts some data from an API and processes it or a set of files for benchmarking.

Any of the repositories made here should contain a readme that details the in- and outputs of the script, its purpose and origin.

Currently this also hosts some smaller miscellaneous data, like network files.

### Publications
Public Group. Contains all the code associated with a given publication and adds some detail in the readme. This is what should be referenced in the paper itself and what others will stumble upon when they read your paper.

All case studies in the publication (that are not under an embargo) should be in this project, such that everyone can very easily rerun these cases. Projects under this group should not be used for version management, only the code that has been used for the paper should be here. Of course a link to the project containing the most recent version with additional features can (and should) be made.

### Archiving

Research Projects and Collaborative Projects that are no longer actively maintained or refined should eventually be archived. Make sure to do so if you're leaving the group and nobody else is continuing that research track.

## Education
Education is cut up in two parts a public and a private group.

The private group contains one repository for each of the courses that are given.
Each repository may contain folders for lectures and exercises with solutions.
Feel free to alter the structure inside of the repository depending on your needs.
Everything that is meant for the students is published on Toledo. On git we only maintain the materials themselves.

The public group contains all of the student projects that we have for subject such as ITS and GIP2. Each of these subject is a group. For ITS each year should be a subgroup within containing the individual projects.
For GIP2 each year is a repository within the group, since it's a single project per year. (To be changed if necessary).
The public group is also where educational materials are kept that are meant to be publicly accessible. This is necessary for working with binder.

It's noteworthy that binary and other custom formats such as .docx, .ppt etc. **cannot** be tracked by git. No Delta can be seen from gits interfaces and the data is always duplicated for each individual commit. Many of our educational materials are in these formats. Git is still useful here though, since it gives us a single spot to record issues with the material, have debates and maintain different versions. The most important benefit may be that there is continuity between different teaching assistants taking over from one another as they join/ leave the lab.

We recommend that for new exercises and if you're reworking sessions anyhow that you use simple text files (markdown) like the one we have here.
However, this is not advisable if you have a lot of citations since there is no interface to citation managers.
For a list of supported functionalities see https://about.gitlab.com/handbook/markdown-guide/.

### Thesis
All theses of our students need to be available on the git in our Theses group.
**It is the main supervisors responsibility to ensure that the students code can be found there.**
Ideally, we have students use the git during the year, as that makes code review by the assistants much easier. Although not all students are comfortable with programming so we leave this up to the assistant to decide.

Embargoed thesis do not end up on our git, the access management is cumbersome. They're handled on a case-by-case basis, make sure to discuss with the contracting company.

### Student Projects

Once again we advise to have the students use git themselves if the time allows this. In any case, **it is the teaching assistants reponsibility to make sure that all student's projects are recorded on the git**.
This includes some adequate documentation, which can be an associated report.
As a frame of reference: Other students should be able to look at the repository understand what it's about and start working from there without needing excessive guidance from a teaching assistant.

## Researcher & Landing Pages

Our public landing page is: https://itscrealab.pages.gitlab.kuleuven.be/pages/
The idea is that all our nice documentation (for public use) is located in one place.

**Each researcher should make a small text about him(her)self** on (https://itscrealab.pages.gitlab.kuleuven.be/pages/page/group/).