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.

This is a **PREVIEW** of version 2.0. The code repository is subject to
significant restructuring before the official version 2.0 debuts. You may
develop based on this version but please do not rely on it for production use,
yet.

Coding Style
============
We target to adopt the 
`PEP 8 -- Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008/>`_. 
New codes should be made 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.

The best way to ensure that your codes can successfully execute on others' machines is to test run your codes inside the docker container.

While it is up to developers to choose their working environment, we recommend the open-source VSCode (Microsoft Visual Studio).

First time Setup
----------------
#.  `Download and install Git <https://git-scm.com>`_
#.  You need to tell Git whom 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/>`_. Please note that to test the SSH key you should use the command ``ssh -T git@com-swirls.org`` instead.
#.  `Download and install Docker <https://www.docker.com>`_
#.  `Download and install VSCode <https://code.visualstudio.com>`_ , along with the following extensions in VSCode:
    
    *   Python by Microsoft
    *   Docker by Microsoft
    *   Preview by Haixin Chen
    
#.  Inside VSCode, press F1 and type `Git: Clone`, then enter `https://com-swirls.org/com-swirls/swirlspy.git` as Repository URL. Navigate to the home directory (if not already) and then click the button "Select Repository Location". Enter your username and password when prompt. 
#.  Inside VSCode, open a new terminal. Type::

        docker login registry.com-swirls.org

    Enter your username and password of GitLab.

Happily Ever After
------------------
#.  Create an Issue on Com-SWIRLS GitLab-CE (`direct link <https://com-swirls.org/com-swirls/swirlspy/issues/new?issue>`_)
#.  Use the pull-down menu to "Create branch" (Here below we assume the branch name is "37-test")
#.  Open a new terminal. Type::

        git fetch
        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
#.  Test it with the provided docker image. Open a new terminal and type::

        docker run -it -v $HOME/swirlspy:/builds/com-swirls/swirlspy registry.com-swirls.org/com-swirls/swirlspy:latest
        conda activate swirlspy

    Note that the git repository is located inside /builds of the container.
#.  Using built-in Git control provided by VSCode, or invoke the following commands with a terminal::

        git stage .
        git commit
        git push origin 37-test

#.  Use a web browser to create a merge request: `<https://com-swirls.org/com-swirls/swirlspy/merge_requests/new>`_
#.  Await approval by Owners or Maintainers. Check with them if your request has not been entertained within a reasonable period of time.
#.  Delete your local branch::
    
        git checkout master
        git branch -D 37-test

#.  Repeat the above.