Advanced Instructions
=====================

**This web page is written primarily for Maintainers. If you only use or contribute, there is no need to read this page.**

Create and Upload Docker image
------------------------------

If you want to include (or exclude) certain packages, you will need to create a new Docker image and upload it into GitLab.

#.  `Install Docker <https://docs.docker.com/get-started/>`_
#.  Create a new directory and `cd` into it
#.  Download the Dockerfile from file repository, or create a file and copy the content into it
#.  Edit Dockerfile to include (or exclude) packages required
#.  Create a docker image by `docker build -t registry.com-swirls.org/com-swirls/swirlspy:latest .` (You may also use VSCode to do so)
#.  Push the docker image onto GitLab.com by `docker push registry.com-swirls.org/com-swirls/swirlspy:latest`
#.  (Optional) Remove the local docker image by `docker rmi -f $(docker images -q -a)`


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.

#.  Enter the docker::

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

#.  Activate 'swirlspy' environment::

        conda activate swirlspy
   
#.  Build::

        conda build /builds/com-swirls/swirlspy/conda.recipe
   
#.  Install::

        conda install --use-local swirlspy


System Development Life Cycle Iterative Model
-----------------------------------------------

The following is 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

Releasing a version
*******************

The following is the suggested procedures 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/doc_branches``. Add the new entry corresponding to the new version
 - Update ``ci/package_branches``. Add the new entry corresponding to the new version
 - Commit ``ci/doc_branches`` and ``ci/package_branches``
 - Push the source code to the GitLab Server
 - Create a merge request for updating ``ci/doc_branches`` and ``ci/package_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
 - Verify the website https://docs.com-swirls.org/