Contributors’ Guide

Versioning

Semantic versioning has been adopted since version 2.1. API would be backward compatible in minor version upgrade.

Coding Style

The Python coding style PEP 8 – Style Guide for Python Code is adopted. New codes should be PEP 8 compliant, while existing codes should be progressively modified to comply with PEP 8.

Philosophy

While deeply appreciate any contribution, we would like you to agree to our design philosophy to ensure long-term maintainability of the codebase.

Modularity: Each and every function/method should do one thing and one thing only, and do it well. Try keep every function/method limited to not more than 25 lines, and under any circumstances less than 50 lines (excluding docstrings)
Readability: You codes will be read by dozens if not hundreds of people. They do not just make the computer works. They are to be appreciated, regularly reviewed and improved upon from time to time. Ensure compliance with PEP8.
Documented: Write docstrings before writing any codes. Always ensure consitencey between codes and documentations.
Traceable: Always create an issue and a merge requeast before working on anything, so that we have a unique identification number for issue tracking and communications.

Workflow

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

While it is up to developers to pick their own code editors, we recommend the open-source VSCode.

(Optional) Install Virtual Machine

Currently, swirlspy supports Linux 64-bit only. If you only have Windows or Mac but no Linux, you may still use swirlspy by installing it on VirtualBox (a VM hypervisor). Instructions are provided below:

Download Oracle VM VirtualBox Manager from this link
Download the latest stable version of Ubuntu Desktop ISO image from this link
Click New on VirtualBox Manager to create a new VM, then type: Linux, version: Ubuntu(64_bit)
Set RAM to 4096 MB (4 GB)
We recommend maxing out System -> Processor (4) and setting Video Memory to 128 MB for reasonable performance
Double click on the new VM, then select the Ubuntu Desktop ISO image
Click on the VM to run it, choose install Ubuntu, adopt default settings
Set up account and password

First time Setup

Download and install Git
You need to tell Git who 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. Kindly note that to test the SSH key you should use the command ssh -T git@com-swirls.org instead.
Download and install VSCode , along with the following extensions in VSCode:
- Python by Microsoft
- Preview by Haixin Chen
Inside VSCode, open a new terminal. Type:
```
git clone git@com-swirls.org:com-swirls/swirlspy.git
cd swirlspy
conda env create -f environment.yml
conda activate swirlspy
```
This will download all the codes from com-swirls.org to your folder swirlspy and then create an environment named swirlspy, which you will use for testing codes.

For Each Development Cycle

Activate the swirlspy environment:
```
conda activate swirlspy
```
Create an Issue on Com-SWIRLS GitLab-CE (direct link)
Click “Create merge request” (Here below assumes the branch name is “37-test”.)
Open a new terminal. Type:
```
git fetch -p
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 or other editors. Remember to comply with PEP 8.
Test your codes and make sure there is no problem or error:
```
pytest (or run your codes by other means)
```

Stage the change, commit with a message, and push back:

git stage .
git commit -m "some commit message"
git push

Goto SwirlsPy’s Merge Request. Find the related issue, and click on “Resolve WIP status” so that Maintainers know you are done.
Await approval by Maintainers. Check with them as and when necesssary.
Repeat the above process.

System Development Life Cycle Iterative Model

The following describes the simple workflow on how to adopt the SDLC iterative model to our project.:

graph TD Init[Initialization] Release[Release a new version] Issue[Owner / Developer create a new issue] CreateBranch[Developer creates a new branch] Fetch[Fetch and checkout the new branch] Update[Update source code] Commit[Commit source code] Push[Push source code] CreateMergeRequest[Developer creates a merge request] Accept{Accept?} Evaluation Init-->Planing Planing-->Requirements Requirements-->|Design|Issue Issue-->|Coding|CreateBranch CreateBranch-->Fetch Fetch-->Update Update-->Commit Commit-->Push Push-->Update Push-->CreateMergeRequest CreateMergeRequest-->Accept Accept-->|No|Update Accept-->|yes,accept by project owner or maintainer|Evaluation Evaluation-->Planing Evaluation-->Release

Advanced Instructions

The following sections are written primarily for Maintainers. If you only use or contribute, there is no need to read further.

Manually Build a SwirlsPy Conda package

The Conda package is now automatically generated. But if you want you can also build one manually, with the following instructions:

This documents how to prepare a conda package for swirlspy.

Activate ‘swirlspy’ environment:
```
conda activate swirlspy
```

Build:

conda build /builds/com-swirls/swirlspy/conda.recipe

Install:
```
conda install --use-local swirlspy
```

Launching a new release

The following is the suggested procedure for releasing a new version of swirlspy based on the culmination of our team’s hard work:

Create a new branch from master (make sure branch name does not match the version format x.x.x)

Fetch the new branch

Update `swirlspy/__init__.py`. Update the version number carefully. ( Reference: https://semver.org/ )

Edit `ci/exclude_branches` if necessary

Commit `swirlspy/__init__.py`

Push the source code to the GitLab Server

Use `git tag` to create a tag with the corresponding version

Push the tag to the origin with `git push origin [tag number]`

Create a merge request for updating the version number

Accept the merge request

Verify the CI/CD result before proceeding to the next step

Execute conda install -c https://username:password@conda.com-swirls.org -c defaults -c conda-forge swirlspy

Execute conda install -c https://username:password@conda.com-swirls.org -c defaults -c conda-forge swirlspy=dev to test the nightly build.

Verify the website https://docs.com-swirls.org/