Contributors' Guide
*******************

Versioning
==========
`Semantic versioning <https://semver.org/>`_
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
<https://www.python.org/dev/peps/pep-0008/>`_ 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
<https://trunkbaseddevelopment.com/>`_ 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 <https://code.visualstudio.com/>`_.

(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 <https://www.virtualbox.org/wiki/Downloads>`_

#.  Download the latest stable version of Ubuntu Desktop ISO image from `this link <https://www.ubuntu.com/download/desktop>`_

#.  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 <https://git-scm.com>`_

#.  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 <https://docs.gitlab.com/ee/ssh/>`_. Kindly note that to test
    the SSH key you should use the command ``ssh -T git@com-swirls.org``
    instead.

#.  `Download and install VSCode <https://code.visualstudio.com>`_ , 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
    <https://com-swirls.org/com-swirls/swirlspy/issues/new?issue>`_)

#.  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
    <https://com-swirls.org/com-swirls/swirlspy/merge_requests>`_. 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.:

.. mermaid::
   :align: center

   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.

#.  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/