Developer Guide
===============

Cloning the repository
----------------------

Please make sure to clone the submodules with:

.. code:: bash

   git clone --recurse-submodules git@gitlab.com:ska-telescope/sdp/ska-sdp-spectral-line-imaging.git

Also make sure to update submodules after every pull with:

.. code:: bash

   git submodule update --init

Installing package and dependencies
-----------------------------------

To install the slurmdeployer package and its dependencies in your python
environment using ``poetry``, simply run

.. code:: bash

   poetry install

Git hooks
---------

To enable ``git-hooks`` for the current repository, run

.. code:: bash

   make dev-git-hooks

The ``pre-commit`` hook is defined for the main branch and is present in
the ``.githooks`` folder. The current ``pre-commit`` hook runs the
following

1. If there is a change in either ``environment.yml`` or
   ``pyproject.toml``, prompt the user to ask whether the local
   environment has been updated.
2. Run ``pylint``, which is set to fail on warnings.

A ``prepare-commit-msg`` hook runs after ``pre-commit`` hook, which
helps to prepare a commit message as per agreed format.

A ``pre-push`` hook checks the gitlab-ci pipeline status, and warns user
if the status is not “success”.

.. note::

   Due to interactiveness of these githooks, it is recommended to
   run all git commands using a terminal. GUI based git applications
   might throw errors.

GPG signing the commits
-----------------------

First, set the git username and email for the your local repository.

.. code:: bash

   git config user.name "username"
   git config user.email "email address"

..

   The git ``user.email`` must match your gitlab account’s email
   address.

Now, enable signing for commits by setting the ``commit.gpgsign`` config
variable to ``true``

.. code:: bash

   git config commit.gpgsign true

Signing with SSH key
~~~~~~~~~~~~~~~~~~~~

To use the ssh-key to sign the commits, set ``gpg.format`` to ssh, and
update ``user.signingkey`` to the path of the ssh public key.

.. code:: bash

   PUB_KEY="path to ssh public key" # set appropriate path

   git config gpg.format ssh
   git config user.signingkey $PUB_KEY

   # Optionally, add your ssh key added into the "allowedSignersFile"
   # gloablly in your home/.config, so that git can trust your ssh key
   mkdir -p ~/.config/git
   EMAIL=$(git config --get user.email)
   echo "$EMAIL $(cat $PUB_KEY)" >> ~/.config/git/allowed-signers
   git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed-signers

Signing with GPG key
~~~~~~~~~~~~~~~~~~~~

To use gpg keys to sign the commits

.. code:: bash

   git config gpg.format openpgp
   git config user.signingkey "GPG KEY" #set GPG key value

Useful commands for developers
------------------------------

This repo contains `SKA ci-cd
makefile <https://gitlab.com/ska-telescope/sdi/ska-cicd-makefile>`__
repository as a submodule, which provides us with some standard commands
out of the box.

It is **recommended** to use these instead of their simpler
counterparts. For example, use ``make python-test`` instead of
``pytest``.

Run ``make help`` to get list of all supported commands. Some of the
mostly used commands are listed below:

.. code:: bash

   # Formatting the code
   make python-format

   # Linting checks
   make python-lint

   # Running tests
   make python-test

   # Generating source files for docs
   make -C docs/ create-doc

   # Building html documentation
   make docs-build html

   # Building oci images
   make oci-build-all