Getting started

Contributions to this API are welcome.

A contribution can be either be a patch or a minor/major feature. Patches include bugfixes and small changes to the code. Features can either be minor or major developments and can include potentially disruptive changes.

Development environment

Clone the repository locally

git clone <ska-src-api-accounting-url>

Initialise submodules for standard make targets and variables

ska-src-api-accounting$ git submodule update --recursive --init

Development cycle

Makefile targets have been included to facilitate easier and more consistent development. The general recipe is as follows:

Depending on what you are working on, fork the project and create a new major/minor/patch branch, e.g.
```
ska-src-api-accounting$ make patch-branch NAME=some-name
```
Note that this both creates and checkouts the branch.
Make your changes.
Create new (OpenAPI) code samples if necessary (requires the service to be running):
```
ska-src-api-accounting$ make code-samples
```

Update poetry.lock

ska-src-api-accounting$ poetry lock --no-update

Add your changes to the branch:
```
ska-src-api-accounting$ git add ...
```
Bump the version and commit, entering a commit message when prompted:
```
ska-src-api-accounting$ make bump-and-commit
```
This is essential to keep version numbers consistent across the helm chart and python package.
Push the changes to your fork when ready:
```
ska-src-api-accounting$ make push
```
Create a merge request against upstream main.

Development tricks

Using poetry

To work inside a poetry shell:

ska-src-api-accounting$ poetry shell

To install dependencies from pyproject.toml:

(venv)ska-src-api-accounting$ poetry install

Managing authorisation

Authorisation is managed by dependencies. See the examples router for how to connect to the Permissions API.

Bypassing AuthN/Z

AuthN/Z can be bypassed for development only by setting DISABLE_AUTHENTICATION=yes in the environment.

Amending charts

The CI/CD pipeline uses templates inherited from the wider SKA project.

If making changes to the chart, it may be necessary to alter the chart parameters that are passed to both the CI/CD pipeline and local deployment.

Common parameters that are passed to both can be altered in testing.mk under the variable K8S_CHART_COMMON_PARAMS. Variables for the CI/CD and local deployments can be found under the variable K8S_CHART_PARAMS under cicd.mk and dev.mk respectively.

Managing connections to other APIs

See the examples router for how to connect to the Site Capabilities API.

Testing

Testing is done via the pytest module, with code coverage provided by the pytest-cov module.

Component testing

Component testing is conducted inside a k8s deployment environment using mocked responses to external services.

The component tests implemented for this repository are stored under the /tests/component directory. These component tests are executed during the test stage of the CI/CD pipeline under the k8s-test-api-with-disabled-auth and k8s-test-api-with-enabled-auth jobs.

For local testing, an environment can be installed via minikube/helm with:

ska-src-api-accounting$ minikube start
ska-src-api-accounting$ make k8s-install-chart

Note that if only tests are modified, it isn’t necessary to run the k8s-install-chart target.

To run the tests locally with both authentication enabled and disabled, respectively:

ska-src-api-accounting$ make k8s-test-auth
ska-src-api-accounting$ make k8s-test-noauth

Code quality

This repository uses the following libraries for code quality:

isort for sorting imports,
black to enforce a consistent coding style,
flake8 to check code base against coding style (PEP8), and
pylint to look for programming errors and code smells

Linting

Operations for code linting are performed by the python-lint Makefile target provided by the .make submodule. This should be run inside a poetry shell, e.g.

$ poetry shell
(ska_src_api_accounting-py3.12) ska_src_api_accounting$ make python-lint

Formatting

Operations for code formatting are performed by the python-format Makefile target provided by the .make submodule. This should be run inside a poetry shell e.g.

$ poetry shell
(ska_src_api_accounting-py3.12) ska_src_api_accounting$ make python-format

Documentation

There is a Makefile target for generating documentation locally:

ska-src-api-accounting/docs$ make html

To render inheritance diagrams etc., the graphviz library must be installed.