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

Versioning
==========
Starting from version 2.1, `Semantic versioning <https://semver.org/>`_
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 
<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.

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/>`_.

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 -n environment.yml
        conda activate swirlspy
        conda install pylint pep8

    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. Also, pylint and pep8 are installed to facilitate
    programming work

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:

**Step 1: Update version number in the source tree**

 - Create a new branch from master
 - Fetch the new branch
 - Update ```swirlspy/__init__.py```. Update the version number carefully. 
   ( Reference: https://semver.org/ )
 - Commit ```swirlspy/__init__.py```
 - 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

**Step 2: Configure CI/CD for handling a new version of the release**

 - Create a new branch from master
 - Fetch the new branch
 - Update ``ci/branches``. Add the new entry corresponding to the new version. 
   The particular branch HEAD should always be located at the bottom of the 
   text file.
 - Commit ``ci/branches``
 - Push the source code to the GitLab Server
 - Create a merge request for updating ``ci/branches``
 - Accept the merge request
 - Verify the website https://conda.com-swirls.org/
 - Execute 
   ``conda install -c https://username:password@conda.com-swirls.org -c defaults -c conda-forge swirlspy`` to verify the installation
 - 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/