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.
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.
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.
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)
- Rightclick Setting -> storage -> Controller IDE -> Add optical drive(1st one) -> select the Ubuntu Desktop ISO image
- Click on the VM to run it, choose install Ubuntu, use default settings
- Set up account and password
First time Setup¶
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 "email@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 firstname.lastname@example.org.
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 email@example.com: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.:
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
conda build /builds/com-swirls/swirlspy/conda.recipe
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
`swirlspy/__init__.py`. Update the version number carefully. ( Reference: https://semver.org/ )
- Push the source code to the GitLab Server
- Create a merge request for updating the version number
- Accept the merge request
- After CI/CD process, use
`git tag`to create a tag with the corresponding version
- Push the tag to the origin
- Verify the CI/CD result before proceeding to the next step
conda install -c https://username:firstname.lastname@example.org -c defaults -c conda-forge swirlspy
conda install -c https://username:email@example.com -c defaults -c conda-forge swirlspy=devto test the nightly build.
- Verify the website https://docs.com-swirls.org/