Contributors’ Guide

Versioning

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

For the current 2.0.x version, backward compatbility will be preserved as much as practicable.

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:

  1. Download Oracle VM VirtualBox Manager from this link
  2. Download the latest stable version of Ubuntu Desktop ISO image from this link
  3. Click New on VirtualBox Manager to create a new VM, then type: Linux, version: Ubuntu(64_bit)
  4. Set RAM to 4096 MB (4 GB)
  5. Rightclick Setting -> storage -> Controller IDE -> Add optical drive(1st one) -> select the Ubuntu Desktop ISO image
  6. Click on the VM to run it, choose install Ubuntu, use default settings
  7. Set up account and password

First time Setup

  1. Download and install Git

  2. 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"
    
  3. 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.

  4. Download and install VSCode , along with the following extensions in VSCode:

    • Python by Microsoft
    • Preview by Haixin Chen
  5. 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

  1. Activate the swirlspy environment:

    conda activate swirlspy
    
  2. Create an Issue on Com-SWIRLS GitLab-CE (direct link)

  3. Click “Create merge request” (Here below assumes the branch name is “37-test”.)

  4. 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.

  5. Edit your codes with VSCode or other editors. Remember to comply with PEP 8.

  6. Test your codes and make sure there is no problem or error:

    pytest (or run your codes by other means)
    
  7. Stage the change, commit with a message, and push back:

    git stage .
    git commit -m "some commit message"
    git push
    
  8. Goto SwirlsPy’s Merge Request. Find the related issue, and click on “Resolve WIP status” so that Maintainers know you are done.

  9. Await approval by Maintainers. Check with them as and when necesssary.

  10. 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<br> a new issue] CreateBranch[Developer creates<br> a new branch] Fetch[Fetch and checkout<br> the new branch] Update[Update source code] Commit[Commit source code] Push[Push source code] CreateMergeRequest[Developer creates<br> 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<br> 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.

  1. Activate ‘swirlspy’ environment:

    conda activate swirlspy
    
  2. Build:

    conda build /builds/com-swirls/swirlspy/conda.recipe
    
  3. 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
  • 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/