GOLEM GitLab housekeeping rules

In a nutshell
What is Git and why do we use it?
How to use Git
How to use the GOLEM Gitlab
Further considerations

In a nutshell

Dirigent is a Git package hosted at GitLab, containing control software for the tokamak GOLEM. It is currently (February 2021) the preferred means of sharing software contributions related to the tokamak. This page details the housekeeping rules of its use.

What is Git and why do we use it?

Git is software which enables large groups to work on a common text-based project (developing software, writing rulebooks, co-authoring articles…) without getting into each other’s way. It’s called a version control system, that is, it keeps track of individual snapshot of the project (software, rulebook, article…) and it records who made what change to it when. It automatically incorporates these changes one by one, allowing others to keep track of what’s happening and reverse or discuss some changes as needed. (It’s actually way more complicated than that - see any Git tutorial under the sun.)

Git is used at GOLEM because it allows multiple people to contribute to the tokamak software (data analysis, homepage building, discharge procedure…) independently and controllably. An alternative would be, for instance, having all the code in a shared Dropbox folder or sharing it via email. (Been there, done that, it was terrible.) The Dirigent package is hosted at GitLab because it’s one of the major sites providing cloud space for Git packages.

How to use Git

Detailed instructions can be found on the internet. You will quickly discover that Git is very complicated. Make a cup of coffee (tea, cocoa, rum and coke, whatever helps you relax and concentrate) and spend 1-3 evenings reading up about Git.

For quick reference, check out the Git commands compiled by Petr Mácha.

How to use the GOLEM Gitlab

Warning: Techno babble ahead. If you understand everything in this section, you have all the Git knowledge you need to use the GOLEM GitLab and contribute to Dirigent.

The current, most up-to-date version of the GOLEM software is stored in the master branch. This is the one which is actually in use. Therefore, your contribution to Dirigent will only take effect (appear on the shot homepage etc.) if you get it inside master. The heavily suggested workflow is to start a new branch from the current master, work on it, push the changes and request its merge into master as soon as possible. Ideally, all this happens within one day. This keeps the number of active branches to a minimum and prevents merge conflicts from arising.

To contribute to Dirigent, you’ll need a GitLab account. You can create a new one, or perhaps you already have one or your institute (such as IPP CAS) provides you with one. Ask Vojtěch Svoboda or Petr Mácha to add you to the team of Dirigent contributors and you’re good to go.

This tutorial shows Git use through the command line on Linux. However, it is also possible to use a GUI (Graphical User Interface). I recommend GitAhead, which works for Windows, Linux and macOS.

To make a contribution to Dirigent, follow approximately these steps (written for the Linux command line):

Go to the Dirigent directory.

cd /desired/path/dirigent

If you don’t have a local copy yet, clone it.

cd /desired/path
git clone https://gitlab.com/golem-tokamak/dirigent.git
cd dirigent

Check the state of the repository.
```
git status
```
You will see if you have any uncommitted changes and what branch you’re on. Let’s suppose that there are some uncommitted changes and that you’re on branch pink_fluffy_unicorn. If you have no uncommitted changes and/or are on the master branch, skip to step 4.
Figure out what you want to do with the changes. For instance:
1. You have run a Python notebook and now it contains cell output. It also created an output file, icon-fig.png.
  -> Run jupyter notebook, clear all of the notebook output and save it. You can either delete icon-fig.png or add it to .gitignore.
2. You have made changes to a Python notebook that you want to keep.
  
  -> Finish up the changes into a working, presentable state. If that will take more time than you care to give right now, you can stash them. Stage the changes, commit them and push them upstream (instructions how to are in step 5). If your work on pink_fluffy_unicorn is done with this, submit a merge request to the master branch indicating you wish to have pink_fluffy_unicorn deleted. If the work you want to do right now is a direct continuation of pink_fluffy_unicorn, you can postpone the merge request and keep working on this branch. Note, however, that you should keep branches as short as possible so that they don’t deviate from master very much.
Check if you have really taken care of all the changes.
```
git status
```
If yes, switch to the master branch.
```
git checkout master
```
Get the up-to-date version of master.
```
git pull
```
Create a new branch starting from master.
```
git branch dancing_on_rainbow
```
Check if you’re on that branch with git status. If not, switch to it.
```
git checkout dancing_on_rainbow
```
Start writing! Make new files, edit old ones, test and develop. When you have created something that makes sense, stage it and commit it.
```
git status
git add . #stage all files which are not tracked yet; alternatively write the file names including paths one by one
git commit -m 'Enable rainbow background'
```
The commit message should be eloquent and telling. Refer to How to Write a Git Commit Message. There’s a chance (albeit not a great one) that one day you’ll need to revert some of the changes. So, if possible, keep it one commit - one logical change.
When you have finished the work you wanted to do, stage, commit and push the changes.
```
git status
git add .
git commit -m 'Fix the bug which swapped indigo and azure'
git push
```
Then go to GitLab, log in and submit a merge request. Tick that you wish to delete the source branch (dancing_on_rainbow, or pink_fluffy_unicorn if you’re still working on that). Even if the next piece of work you do on Dirigent is a direct successor of this branch, you’ll still want to start over by creating a new branch from master, even if you should name it the same. This keeps the branches as short as possible.
Your changes to Dirigent will take effect in the tokamak after they are merged into the master branch.

Further considerations

Python notebooks: always clear their output before committing them. The output can be pretty big size-wise and it seriously clutters up the difference between two subsequent notebook versions.

Interactive Python notebook plots: If you’re running a Python notebook on your computer, you can make the plots interactive (changing axes span etc.) by writing %matplotlib notebook at the beginning of the notebook. This option, however, won’t work with the scripts hosted on the homepage (such as OnStage scripts). There, one has to use %matplotlib inline, which renders static plots. It is still possible to create interactive OnStage script plots by using the holoviews library. For a working example, refer to the basic diagnostics script of shot #35419.