Contributors’ Guide

Versioning

Starting from version 2.1, Semantic versioning will be adopted, which means API would be backward compatible in minor version upgrade.

This is a PREVIEW of version 2.0. The code repository is subject to significant restructuring before the official version 2.0 debuts. You may develop based on this version but please do not rely on it for production use, yet.

Coding Style

We target to adopt the PEP 8 – Style Guide for Python Code. New codes should be made PEP 8 compliant, while existing codes should be progressively modified to comply with PEP 8.

Workflow

The Trunk Based Development Workflow Model is adopted. This workflow model is the simplest model that works.

The best way to ensure that your codes can successfully execute on others’ machines is to test run your codes inside the docker container.

While it is up to developers to choose their working environment, we recommend the open-source VSCode (Microsoft Visual Studio).

First time Setup

Download and install Git
You need to tell Git whom you are. Open a terminal and invoke the following commands: (Remember to use your actual email address and name!):
```
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
```
You also need to setup a SSH key so that you can push back to the Gitlab repository. Please refer to this guide. Please note that to test the SSH key you should use the command ssh -T git@com-swirls.org instead.
Download and install Docker
Download and install VSCode , along with the following extensions in VSCode:
- Python by Microsoft
- Docker by Microsoft
- Preview by Haixin Chen
Inside VSCode, press F1 and type Git: Clone, then enter https://com-swirls.org/com-swirls/swirlspy.git as Repository URL. Navigate to the home directory (if not already) and then click the button “Select Repository Location”. Enter your username and password when prompt.
Inside VSCode, open a new terminal. Type:
```
docker login registry.com-swirls.org
```
Enter your username and password of GitLab.

Happily Ever After

Create an Issue on Com-SWIRLS GitLab-CE (direct link)
Use the pull-down menu to “Create branch” (Here below we assume the branch name is “37-test”)
Open a new terminal. Type:
```
git fetch
git checkout 37-test
```
This pulls the remote branch 37-test into your computer so that you can work on it.
Edit your codes with VSCode
Test it with the provided docker image. Open a new terminal and type:
```
docker run -it -v $HOME/swirlspy:/builds/com-swirls/swirlspy registry.com-swirls.org/com-swirls/swirlspy:latest
conda activate swirlspy
```
Note that the git repository is located inside /builds of the container.
Using built-in Git control provided by VSCode, or invoke the following commands with a terminal:
```
git stage .
git commit
git push origin 37-test
```
Use a web browser to create a merge request: https://com-swirls.org/com-swirls/swirlspy/merge_requests/new
Await approval by Owners or Maintainers. Check with them if your request has not been entertained within a reasonable period of time.

Delete your local branch:

git checkout master
git branch -D 37-test

Repeat the above.