Developer Guide

Cloning the repository

Please make sure to clone the submodules with:

git clone --recurse-submodules git@gitlab.com:ska-telescope/sdp/ska-sdp-exec-piper.git

Also make sure to update submodules after every pull with:

git submodule update --init

Setting up environment using Poetry

Install poetry standalone by following official instructions on their website. Then, you can run poetry install. This will:

Create a new virtual environment (either in project or some shard poetry directory)
Install all the dependency groups defined in pyproject.toml

Git hooks

To enable git-hooks for the current repository, run

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

If there is a change in pyproject.toml, prompt the user to ask whether the local environment has been updated.
Run pylint, which is set to fail on warnings.
Run pytest, with coverage not to fall below 80%.
Build documentation

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.

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

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.

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

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 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:

# 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

Making a release

Pre-requisites

Run make make to update the .make submodule to latest master commit.

Release guidelines

We follow the guidelines for a release given on this page.

Following steps are simplified, and specific for this repository:

Make sure that all the changes are commited, and the local git working area is clean. Since we follow trunk based development, the active branch should be the main branch.
Check the current version using make show-version.
To bump up the release, run either one of the following commands
```
make bump-patch-release
make bump-minor-release
make bump-major-release
```
Above commands automtically should update the version information in following files:
- .release
- pyproject.toml
- docs/src/conf.py ('release' and 'version' variable)
If it doesn't happen automtically, please make mannual changes.

The make show-version command should now show the next version. Use this version for all the later changes.
Apart from above files, we need to update __version__ variable in following modules:
- src/ska_sdp_piper/__init__.py
Add a new H2 (##) heading in CHANGELOG.md, and add release notes under that heading. The heading should be the new version number.
Using the new version, create a new issue on the Release Management Jira Project with a summary of your release, and set it to "IN PROGRESS".
Stage all the changes, create a new commit with:
1. The JIRA Ticket ID = ID of the release issue created in previous step.
2. The commit message title = "Bump version to V.V.V"
Push the changes to the main branch. Make sure that the pipeline is green.
Create a git-tag for the new version using make create-git-tag command.
Run make push-git-tag to push the tag to main branch.